{"openapi":"3.0.0","paths":{"/v1/products":{"get":{"operationId":"PublicProductsController_findProducts","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (starts from 1)","schema":{"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"default":10,"example":10,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Field to sort by","schema":{"default":"createdAt","example":"createdAt","type":"string"}},{"name":"sortDir","required":false,"in":"query","description":"Sort direction (asc or desc)","schema":{"default":"ASC","example":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"keyword","required":false,"in":"query","description":"Keyword to filter categories (minimum 3 characters)","schema":{"example":"electronics","type":"string"}},{"name":"sku","required":false,"in":"query","description":"Filter by exact SKU match","schema":{"example":"PROD-001","type":"string"}},{"name":"handle","required":false,"in":"query","description":"Filter by exact handle/slug match","schema":{"example":"my-product","type":"string"}},{"name":"barcode","required":false,"in":"query","description":"Filter by exact barcode match","schema":{"example":"1234567890123","type":"string"}}],"responses":{"200":{"description":"Returns paginated products"},"401":{"description":"Unauthorized"}},"security":[{"bearer":[]}],"summary":"Search/list products","tags":["Products"]},"post":{"operationId":"PublicProductsController_create","parameters":[],"responses":{"201":{"description":"Product created"},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized"}},"security":[{"bearer":[]}],"summary":"Create product","tags":["Products"]}},"/v1/products/sync":{"get":{"operationId":"PublicProductsController_findProductsForSync","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (starts from 1)","schema":{"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"default":10,"example":10,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Field to sort by","schema":{"default":"createdAt","example":"createdAt","type":"string"}},{"name":"sortDir","required":false,"in":"query","description":"Sort direction (asc or desc)","schema":{"default":"ASC","example":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"keyword","required":false,"in":"query","description":"Keyword to filter categories (minimum 3 characters)","schema":{"example":"electronics","type":"string"}},{"name":"sku","required":false,"in":"query","description":"Filter by exact SKU match","schema":{"example":"PROD-001","type":"string"}},{"name":"handle","required":false,"in":"query","description":"Filter by exact handle/slug match","schema":{"example":"my-product","type":"string"}},{"name":"barcode","required":false,"in":"query","description":"Filter by exact barcode match","schema":{"example":"1234567890123","type":"string"}}],"responses":{"200":{"description":"Returns paginated products optimized for sync"}},"security":[{"bearer":[]}],"summary":"List products for sync (lightweight)","tags":["Products"]}},"/v1/products/batch-lookup":{"post":{"operationId":"PublicProductsController_batchLookup","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchLookupDto"}}}},"responses":{"200":{"description":"Returns map of matchValue → productId"},"401":{"description":"Unauthorized"}},"security":[{"bearer":[]}],"summary":"Batch lookup product IDs by field","tags":["Products"]}},"/v1/products/bulk-update":{"patch":{"operationId":"PublicProductsController_bulkUpdate","parameters":[],"responses":{"200":{"description":"Returns per-product results"},"400":{"description":"Exceeds max batch size (50)"},"401":{"description":"Unauthorized"}},"security":[{"bearer":[]}],"summary":"Bulk update products (max 50)","tags":["Products"]}},"/v1/products/{id}":{"get":{"operationId":"PublicProductsController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Returns product details"},"401":{"description":"Unauthorized"},"404":{"description":"Product not found"}},"security":[{"bearer":[]}],"summary":"Get single product","tags":["Products"]},"patch":{"operationId":"PublicProductsController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Product updated"},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized"},"404":{"description":"Product not found"}},"security":[{"bearer":[]}],"summary":"Update product","tags":["Products"]}},"/v1/orders":{"get":{"operationId":"PublicOrdersController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (starts from 1)","schema":{"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"default":10,"example":10,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Field to sort by","schema":{"default":"createdAt","example":"createdAt","type":"string"}},{"name":"sortDir","required":false,"in":"query","description":"Sort direction (asc or desc)","schema":{"default":"ASC","example":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"keyword","required":false,"in":"query","description":"Keyword to filter categories (minimum 3 characters)","schema":{"example":"electronics","type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by order status","schema":{"example":"pending","type":"string"}},{"name":"customerId","required":false,"in":"query","description":"Filter by customer ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"dateFrom","required":false,"in":"query","description":"Filter orders created on or after this date (ISO 8601)","schema":{"example":"2025-01-01","type":"string"}},{"name":"dateTo","required":false,"in":"query","description":"Filter orders created on or before this date (ISO 8601)","schema":{"example":"2025-12-31","type":"string"}}],"responses":{"200":{"description":"Returns paginated orders"},"401":{"description":"Unauthorized"}},"security":[{"bearer":[]}],"summary":"List orders","tags":["Orders"]},"post":{"description":"Create an order from a marketplace integration (e.g. eBay, Amazon). Supports externalId for deduplication.","operationId":"PublicOrdersController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePublicOrderDto"}}}},"responses":{"201":{"description":"Order created"},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized"},"409":{"description":"Order with this externalId already exists"}},"security":[{"bearer":[]}],"summary":"Create order","tags":["Orders"]}},"/v1/orders/{id}":{"get":{"operationId":"PublicOrdersController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Returns order details"},"401":{"description":"Unauthorized"},"404":{"description":"Order not found"}},"security":[{"bearer":[]}],"summary":"Get single order","tags":["Orders"]},"patch":{"description":"Update an order's status, payment status, or notes — e.g. when a marketplace fulfilment or cancellation changes. Pricing, line items, currency, and addresses are not editable here.","operationId":"PublicOrdersController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePublicOrderDto"}}}},"responses":{"200":{"description":"Order updated"},"400":{"description":"Invalid update (order is canceled/refunded, or a sealed field on a paid + fulfilled order)"},"401":{"description":"Unauthorized"},"403":{"description":"Order does not belong to the authenticated store"},"404":{"description":"Order not found"}},"security":[{"bearer":[]}],"summary":"Update order status","tags":["Orders"]}},"/v1/customers":{"get":{"operationId":"PublicCustomersController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (starts from 1)","schema":{"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"default":10,"example":10,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Field to sort by","schema":{"default":"createdAt","example":"createdAt","type":"string"}},{"name":"sortDir","required":false,"in":"query","description":"Sort direction (asc or desc)","schema":{"default":"ASC","example":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"keyword","required":false,"in":"query","description":"Keyword to filter categories (minimum 3 characters)","schema":{"example":"electronics","type":"string"}},{"name":"accountStatus","required":false,"in":"query","description":"Filter by account status","schema":{"example":"registered","type":"string","enum":["registered","guest"]}}],"responses":{"200":{"description":"Returns paginated customers"},"401":{"description":"Unauthorized"}},"security":[{"bearer":[]}],"summary":"List customers","tags":["Customers"]},"post":{"operationId":"PublicCustomersController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomerDto"}}}},"responses":{"201":{"description":"Customer created"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"}},"security":[{"bearer":[]}],"summary":"Create a customer","tags":["Customers"]}},"/v1/customers/by-email/{email}":{"get":{"operationId":"PublicCustomersController_findByEmail","parameters":[{"name":"email","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Returns customer details"},"401":{"description":"Unauthorized"},"404":{"description":"Customer not found"}},"security":[{"bearer":[]}],"summary":"Get customer by email","tags":["Customers"]}},"/v1/customers/{id}":{"get":{"operationId":"PublicCustomersController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Returns customer details"},"401":{"description":"Unauthorized"},"404":{"description":"Customer not found"}},"security":[{"bearer":[]}],"summary":"Get single customer","tags":["Customers"]},"patch":{"operationId":"PublicCustomersController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomerDto"}}}},"responses":{"200":{"description":"Customer updated"},"401":{"description":"Unauthorized"},"403":{"description":"Customer belongs to another store"},"404":{"description":"Customer not found"}},"security":[{"bearer":[]}],"summary":"Update a customer","tags":["Customers"]},"delete":{"operationId":"PublicCustomersController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Customer deleted"},"401":{"description":"Unauthorized"},"403":{"description":"Customer belongs to another store"},"404":{"description":"Customer not found"}},"security":[{"bearer":[]}],"summary":"Delete a customer","tags":["Customers"]}},"/v1/taxonomies":{"get":{"operationId":"PublicTaxonomiesController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (starts from 1)","schema":{"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"default":10,"example":10,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Field to sort by","schema":{"default":"createdAt","example":"createdAt","type":"string"}},{"name":"sortDir","required":false,"in":"query","description":"Sort direction (asc or desc)","schema":{"default":"ASC","example":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"keyword","required":false,"in":"query","description":"Keyword to filter categories (minimum 3 characters)","schema":{"example":"electronics","type":"string"}},{"name":"parentId","required":false,"in":"query","description":"Filter by parent taxonomy ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"type","required":false,"in":"query","description":"Filter by taxonomy type","schema":{"example":"product","type":"string","enum":["product","store","blog","theme","template","app","kb","other"]}}],"responses":{"200":{"description":"Returns paginated taxonomies"},"401":{"description":"Unauthorized"}},"security":[{"bearer":[]}],"summary":"List taxonomies","tags":["Taxonomies"]}},"/v1/taxonomies/by-handle/{handle}":{"get":{"operationId":"PublicTaxonomiesController_findByHandle","parameters":[{"name":"handle","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Returns taxonomy details"},"401":{"description":"Unauthorized"},"404":{"description":"Taxonomy not found"}},"security":[{"bearer":[]}],"summary":"Get taxonomy by handle","tags":["Taxonomies"]}},"/v1/taxonomies/{id}":{"get":{"operationId":"PublicTaxonomiesController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Returns taxonomy details"},"401":{"description":"Unauthorized"},"404":{"description":"Taxonomy not found"}},"security":[{"bearer":[]}],"summary":"Get single taxonomy","tags":["Taxonomies"]}},"/v1/tracking-scripts/snapchat":{"get":{"operationId":"PublicTrackingScriptsController_getSnapchat","parameters":[],"responses":{"200":{"description":"Returns Snap Pixel or null"}},"security":[{"bearer":[]}],"summary":"Get the active Snapchat Pixel for the requesting store","tags":["Tracking Scripts"]},"put":{"operationId":"PublicTrackingScriptsController_upsertSnapchat","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertSnapchatPixelDto"}}}},"responses":{"200":{"description":"Snap Pixel persisted"}},"security":[{"bearer":[]}],"summary":"Upsert the Snapchat Pixel ID for the requesting store","tags":["Tracking Scripts"]},"delete":{"operationId":"PublicTrackingScriptsController_removeSnapchat","parameters":[],"responses":{"200":{"description":"Snap Pixel removed"}},"security":[{"bearer":[]}],"summary":"Remove the Snapchat Pixel for the requesting store","tags":["Tracking Scripts"]}},"/v1/settings":{"get":{"operationId":"PublicSettingsController_getSettings","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get the installation settings","tags":["Settings"]},"put":{"operationId":"PublicSettingsController_updateSettings","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Replace the installation settings","tags":["Settings"]}},"/v1/webhooks":{"post":{"operationId":"PublicWebhooksController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOutboundWebhookSubscriptionDto"}}}},"responses":{"201":{"description":"Subscription created"},"400":{"description":"Invalid topic or URL"},"403":{"description":"Missing required scope for topic"},"409":{"description":"Already subscribed to this topic"}},"security":[{"bearer":[]}],"summary":"Subscribe to a webhook topic","tags":["Webhooks"]},"get":{"operationId":"PublicWebhooksController_list","parameters":[],"responses":{"200":{"description":"Returns subscriptions list"}},"security":[{"bearer":[]}],"summary":"List webhook subscriptions for this plugin","tags":["Webhooks"]}},"/v1/webhooks/{id}":{"delete":{"operationId":"PublicWebhooksController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Subscription deleted"},"403":{"description":"Not authorized"},"404":{"description":"Subscription not found"}},"security":[{"bearer":[]}],"summary":"Unsubscribe from a webhook topic","tags":["Webhooks"]}},"/v1/webhooks/{id}/deliveries":{"get":{"operationId":"PublicWebhooksController_deliveries","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Returns delivery history"}},"security":[{"bearer":[]}],"summary":"Get recent delivery history for a subscription","tags":["Webhooks"]}},"/v1/billing/charge":{"post":{"operationId":"PublicBillingController_createCharge","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateChargeDto"}}}},"responses":{"201":{"description":"Charge created"},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized"}},"security":[{"bearer":[]}],"summary":"Create a one-time charge","tags":["Billing"]}},"/v1/billing/subscription":{"post":{"operationId":"PublicBillingController_createSubscription","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubscriptionDto"}}}},"responses":{"201":{"description":"Subscription created"},"400":{"description":"Invalid request or subscription already exists"},"401":{"description":"Unauthorized"}},"security":[{"bearer":[]}],"summary":"Create a subscription","tags":["Billing"]},"delete":{"operationId":"PublicBillingController_cancelSubscription","parameters":[],"responses":{"200":{"description":"Subscription cancelled"},"401":{"description":"Unauthorized"},"404":{"description":"Subscription not found"}},"security":[{"bearer":[]}],"summary":"Cancel a subscription at period end","tags":["Billing"]}},"/v1/billing/restore":{"post":{"description":"Restores a subscription that was scheduled for cancellation. Only works before period end.","operationId":"PublicBillingController_restoreSubscription","parameters":[],"responses":{"200":{"description":"Subscription restored"},"400":{"description":"Cannot restore subscription"},"401":{"description":"Unauthorized"}},"security":[{"bearer":[]}],"summary":"Restore a subscription scheduled for cancellation","tags":["Billing"]}},"/v1/billing/status":{"get":{"operationId":"PublicBillingController_getSubscriptionStatus","parameters":[],"responses":{"200":{"description":"Returns subscription status"},"401":{"description":"Unauthorized"}},"security":[{"bearer":[]}],"summary":"Get subscription status","tags":["Billing"]}},"/v1/billing/has-subscription":{"get":{"operationId":"PublicBillingController_hasActiveSubscription","parameters":[],"responses":{"200":{"description":"Returns boolean"},"401":{"description":"Unauthorized"}},"security":[{"bearer":[]}],"summary":"Check if an active subscription exists","tags":["Billing"]}},"/v1/billing/plans":{"get":{"operationId":"PublicBillingController_getPlans","parameters":[],"responses":{"200":{"description":"Returns array of plans"},"401":{"description":"Unauthorized"}},"security":[{"bearer":[]}],"summary":"Get all pricing plans for this plugin","tags":["Billing"]}},"/v1/billing/payment-methods":{"get":{"operationId":"PublicBillingController_getPaymentMethods","parameters":[],"responses":{"200":{"description":"Returns array of payment methods"},"401":{"description":"Unauthorized"}},"security":[{"bearer":[]}],"summary":"Get saved payment methods for the store","tags":["Billing"]}},"/v1/billing/subscribe-to-plan":{"post":{"operationId":"PublicBillingController_subscribeToPlan","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeToPlanDto"}}}},"responses":{"201":{"description":"Subscription created"},"400":{"description":"Invalid plan or price"},"401":{"description":"Unauthorized"},"404":{"description":"Plan or price not found"}},"security":[{"bearer":[]}],"summary":"Subscribe to a specific plan","tags":["Billing"]}},"/v1/billing/change-plan":{"post":{"description":"Upgrades or downgrades the current subscription to a new plan with proration","operationId":"PublicBillingController_changePlan","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangePlanDto"}}}},"responses":{"200":{"description":"Plan changed successfully"},"400":{"description":"Invalid plan or no active subscription"},"401":{"description":"Unauthorized"},"404":{"description":"Plan not found"}},"security":[{"bearer":[]}],"summary":"Change subscription plan (upgrade/downgrade)","tags":["Billing"]}},"/oauth/verify-token":{"post":{"operationId":"OAuthController_verifyToken","parameters":[{"name":"authorization","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"Token is valid; returns payload"},"401":{"description":"Token is missing or invalid"}},"summary":"Verify a plugin token","tags":["OAuth"]}},"/oauth/token/refresh":{"post":{"operationId":"OAuthController_refreshToken","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshPluginTokenDto"}}}},"responses":{"200":{"description":"Returns a rotated token pair"}},"summary":"Refresh a plugin access token","tags":["OAuth"]}},"/oauth/token/exchange":{"post":{"operationId":"OAuthController_exchangeToken","parameters":[{"name":"authorization","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"Returns an access + refresh token pair"}},"summary":"Exchange a session token for an access+refresh pair","tags":["OAuth"]}}},"info":{"title":"Orbit Commerce Public API","description":"Public REST API (v1) for 3rd-party plugin & integration developers. Authenticated with a plugin access token; access is gated by OAuth scopes.","version":"v1","contact":{}},"tags":[],"servers":[],"components":{"securitySchemes":{"plugin-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"BatchLookupDto":{"type":"object","properties":{"field":{"type":"string","description":"Product field to match against","enum":["sku","handle","barcode"],"example":"sku"},"values":{"description":"Values to look up (max 200)","example":["PROD-001","PROD-002"],"type":"array","items":{"type":"string"}}},"required":["field","values"]},"PluginOrderItemDto":{"type":"object","properties":{"productId":{"type":"string","description":"Orbit product ID"},"productVariantId":{"type":"string","description":"Orbit product variant ID"},"name":{"type":"string","description":"Item display name"},"sku":{"type":"string","description":"Item SKU"},"quantity":{"type":"number","description":"Quantity","minimum":1},"price":{"type":"number","description":"Unit price","minimum":0},"discount":{"type":"number","description":"Discount amount","default":0},"tax":{"type":"number","description":"Tax amount","default":0}},"required":["name","quantity","price"]},"CreatePublicOrderDto":{"type":"object","properties":{"email":{"type":"string","description":"Customer email address"},"customerId":{"type":"string","description":"Existing Orbit customer ID"},"currencyId":{"type":"string","description":"Currency ID (e.g. UUID of the currency)"},"shippingAmount":{"type":"number","description":"Shipping amount","minimum":0},"taxAmount":{"type":"number","description":"Tax amount","default":0},"discountAmount":{"type":"number","description":"Discount amount","default":0},"paymentStatus":{"type":"string","description":"Payment status","enum":["pending","processing","succeeded","failed","canceled","paid","awaiting_payment","refunded","partially_refunded","partially_paid","disputed","authorized","captured","expired"],"default":"pending"},"notes":{"type":"string","description":"Order notes"},"billingAddressId":{"type":"string","description":"Billing address ID"},"shippingAddressId":{"type":"string","description":"Shipping address ID"},"shippingMethodId":{"type":"string","description":"Shipping method ID"},"items":{"description":"Order line items","type":"array","items":{"$ref":"#/components/schemas/PluginOrderItemDto"}},"externalId":{"type":"string","description":"External order ID from the source marketplace (e.g. eBay order ID, Amazon order ID). Used for deduplication — if an order with this externalId already exists for the store, the request will be rejected."},"source":{"type":"string","description":"Source of the order (e.g. \"ebay\", \"amazon\"). Stored in metadata."},"metadata":{"type":"object","description":"Arbitrary metadata for marketplace-specific data (e.g. marketplace order status, buyer info, fulfillment channel)"}},"required":["email","currencyId","shippingAmount","items"]},"UpdatePublicOrderDto":{"type":"object","properties":{"status":{"type":"string","description":"Order status","enum":["pending","processing","awaiting_balance","completed","canceled","refunded"]},"paymentStatus":{"type":"string","description":"Payment status","enum":["pending","processing","succeeded","failed","canceled","paid","awaiting_payment","refunded","partially_refunded","partially_paid","disputed","authorized","captured","expired"]},"notes":{"type":"string","description":"Order notes"}}},"CreateCustomerAddressDto":{"type":"object","properties":{"firstName":{"type":"string","description":"Address first name","example":"John"},"lastName":{"type":"string","description":"Address last name","example":"Doe"},"company":{"type":"string","description":"Company name","example":"Acme Corp"},"address1":{"type":"string","description":"Primary address line","example":"123 Main Street"},"address2":{"type":"string","description":"Secondary address line","example":"Apt 4B"},"countryId":{"type":"string","description":"Country ID","example":"123e4567-e89b-12d3-a456-426614174000"},"stateId":{"type":"string","description":"State/Province ID","example":"123e4567-e89b-12d3-a456-426614174000"},"stateName":{"type":"string","description":"State/Province name (free-form text)","example":"California"},"cityId":{"type":"string","description":"City ID","example":"123e4567-e89b-12d3-a456-426614174000"},"cityName":{"type":"string","description":"City name (free-form text)","example":"San Francisco"},"postalCode":{"type":"string","description":"Postal/ZIP code","example":"12345"},"phoneCountryCode":{"type":"string","description":"Phone country code","example":"+62"},"phone":{"type":"string","description":"Phone number (without country code)","example":"81234567890"},"isDefaultShipping":{"type":"boolean","description":"Set as default shipping address","example":true},"isDefaultBilling":{"type":"boolean","description":"Set as default billing address","example":true}}},"CreateCustomerDto":{"type":"object","properties":{"storeId":{"type":"string","description":"Store ID that owns this customer","example":"123e4567-e89b-12d3-a456-426614174000"},"firstName":{"type":"string","description":"Customer first name","example":"John"},"lastName":{"type":"string","description":"Customer last name","example":"Doe"},"email":{"type":"string","description":"Customer email address","example":"john.doe@example.com"},"phoneCountryCode":{"type":"string","description":"Phone country code","example":"+62"},"phone":{"type":"string","description":"Phone number (without country code)","example":"81234567890"},"notes":{"type":"string","description":"Notes about the customer","example":"VIP customer, prefers express shipping"},"userId":{"type":"string","description":"Associated user ID if customer has an account","example":"123e4567-e89b-12d3-a456-426614174000"},"address":{"description":"Customer default address (optional)","allOf":[{"$ref":"#/components/schemas/CreateCustomerAddressDto"}]},"tags":{"description":"Tags associated with the customer","example":[{"id":"123e4567-e89b-12d3-a456-426614174000","name":"VIP"},{"id":"123e4567-e89b-12d3-a456-426614174001","name":"Newsletter Subscriber"}],"items":{"type":"array","items":{"type":"a"}},"type":"array"},"marketingEmailConsent":{"type":"boolean","description":"Customer consent for email marketing","example":true},"marketingSmsConsent":{"type":"boolean","description":"Customer consent for SMS marketing","example":false},"taxExempt":{"type":"boolean","description":"Whether the customer is tax-exempt. When true the tax engine bypasses this customer (e.g. resellers, charities, intra-EU B2B with valid VAT ID).","example":false}},"required":["storeId","firstName","lastName","email"]},"UpdateCustomerDto":{"type":"object","properties":{"storeId":{"type":"string","description":"Store ID that owns this customer","example":"123e4567-e89b-12d3-a456-426614174000"},"firstName":{"type":"string","description":"Customer first name","example":"John"},"lastName":{"type":"string","description":"Customer last name","example":"Doe"},"email":{"type":"string","description":"Customer email address","example":"john.doe@example.com"},"phoneCountryCode":{"type":"string","description":"Phone country code","example":"+62"},"phone":{"type":"string","description":"Phone number (without country code)","example":"81234567890"},"notes":{"type":"string","description":"Notes about the customer","example":"VIP customer, prefers express shipping"},"userId":{"type":"string","description":"Associated user ID if customer has an account","example":"123e4567-e89b-12d3-a456-426614174000"},"address":{"description":"Customer default address (optional)","allOf":[{"$ref":"#/components/schemas/CreateCustomerAddressDto"}]},"tags":{"description":"Tags associated with the customer","example":[{"id":"123e4567-e89b-12d3-a456-426614174000","name":"VIP"},{"id":"123e4567-e89b-12d3-a456-426614174001","name":"Newsletter Subscriber"}],"items":{"type":"array","items":{"type":"a"}},"type":"array"},"marketingEmailConsent":{"type":"boolean","description":"Customer consent for email marketing","example":true},"marketingSmsConsent":{"type":"boolean","description":"Customer consent for SMS marketing","example":false},"taxExempt":{"type":"boolean","description":"Whether the customer is tax-exempt. When true the tax engine bypasses this customer (e.g. resellers, charities, intra-EU B2B with valid VAT ID).","example":false}}},"UpsertSnapchatPixelDto":{"type":"object","properties":{}},"CreateOutboundWebhookSubscriptionDto":{"type":"object","properties":{}},"CreateChargeDto":{"type":"object","properties":{"name":{"type":"string","description":"Display name for the charge"},"amount":{"type":"number","description":"Amount to charge","minimum":0.5},"currency":{"type":"string","description":"Currency code (e.g., GBP)"},"paymentMethodId":{"type":"string","description":"UUID of saved payment method (from subscription_payment_methods)"},"returnUrl":{"type":"string","description":"URL to redirect after successful payment (for confirmation page)"},"cancelUrl":{"type":"string","description":"URL to redirect if payment is cancelled"}},"required":["name","amount","currency","paymentMethodId"]},"CreateSubscriptionDto":{"type":"object","properties":{"planCode":{"type":"string","description":"Internal plan code (e.g., basic, pro)"},"planName":{"type":"string","description":"Display name for the plan"},"amount":{"type":"number","description":"Amount to charge per interval","minimum":0.5},"currency":{"type":"string","description":"Currency code (e.g., GBP)"},"interval":{"type":"string","enum":["monthly","yearly"],"description":"Billing interval"},"paymentMethodId":{"type":"string","description":"UUID of saved payment method (from subscription_payment_methods)"},"returnUrl":{"type":"string","description":"URL to redirect after successful subscription (for confirmation page)"},"cancelUrl":{"type":"string","description":"URL to redirect if subscription is cancelled"}},"required":["planCode","planName","amount","currency","interval","paymentMethodId"]},"SubscribeToPlanDto":{"type":"object","properties":{"planId":{"type":"string","description":"UUID of the plan to subscribe to","example":"550e8400-e29b-41d4-a716-446655440000"},"priceId":{"type":"string","description":"UUID of the specific price to use (optional, defaults to monthly GBP)","example":"550e8400-e29b-41d4-a716-446655440001"},"paymentMethodId":{"type":"string","description":"UUID of saved payment method (from subscription_payment_methods)"},"returnUrl":{"type":"string","description":"URL to redirect after successful subscription (for confirmation page)"},"cancelUrl":{"type":"string","description":"URL to redirect if subscription is cancelled"}},"required":["planId","paymentMethodId"]},"ChangePlanDto":{"type":"object","properties":{"planId":{"type":"string","description":"UUID of the new plan to switch to","example":"550e8400-e29b-41d4-a716-446655440000"},"priceId":{"type":"string","description":"UUID of the specific price to use (optional, defaults to same billing period)","example":"550e8400-e29b-41d4-a716-446655440001"}},"required":["planId"]},"RefreshPluginTokenDto":{"type":"object","properties":{}}}}}