> ## Documentation Index > Fetch the complete documentation index at: https://docs.sideshift.app/llms.txt > Use this file to discover all available pages before exploring further. # Submit or update a verified order > Call from a trusted server after payment verification. Maximum 256 KiB; 600 requests per minute per store. Order identity is unique within the authenticated store. Preserve original purchase fields on retries and refunds. There is no dry-run parameter. ## OpenAPI ````yaml /openapi/commerce-orders.yaml post /orders openapi: 3.0.3 info: title: SideShift Orders API version: 1.0.0 description: >- Verified custom-store purchases and cumulative refunds. Uses a store Orders API key, not platform OAuth. Store tracking must be enabled. servers: - url: https://app.sideshift.app/api/commerce security: - StoreOrdersKey: [] paths: /orders: post: tags: - Orders summary: Submit or update a verified order description: >- Call from a trusted server after payment verification. Maximum 256 KiB; 600 requests per minute per store. Order identity is unique within the authenticated store. Preserve original purchase fields on retries and refunds. There is no dry-run parameter. operationId: submitVerifiedStoreOrder requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VerifiedOrder' example: orderId: order-1042 visitorId: 8ac8d41e-8e6e-433c-bec7-19c4e027f2e7 totalCents: 6500 refundedCents: 0 currency: USD occurredAt: '2026-09-11T12:30:00.000Z' status: paid items: - productId: shirt-blue title: Blue shirt quantity: 2 priceCents: 3250 responses: '200': description: >- Accepted. duplicate is true for both replays and updates to existing orders. Acceptance does not guarantee creator attribution, payout, or advertising delivery. content: application/json: schema: type: object required: - accepted - duplicate - orderId properties: accepted: type: boolean enum: - true duplicate: type: boolean orderId: type: string nullable: true description: >- Internal SideShift order ID, or null when privacy-redacted data is suppressed. example: accepted: true duplicate: false orderId: 9ec67b93-ed49-49d6-aa0e-c420d9498673 '400': description: Invalid JSON or request fields. Correct the payload. content: application/json: schema: type: object properties: error: type: string description: Human-readable error message. '401': description: Missing, invalid, rotated, or disconnected-store Orders API key. content: application/json: schema: type: object properties: error: type: string description: Human-readable error message. '404': description: Store tracking is not enabled for this deployment. content: application/json: schema: type: object properties: error: type: string '409': description: >- The existing order has different original amount, currency, payment time, or checkout identity. content: application/json: schema: type: object properties: error: type: string description: Human-readable error message. '413': description: Request exceeds 256 KiB. content: application/json: schema: type: object properties: error: type: string description: Human-readable error message. '429': description: Rate limit exceeded. Honor Retry-After. content: application/json: schema: type: object properties: error: type: string description: Human-readable error message. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 '500': description: Internal error. Retry with stable purchase identity and backoff. content: application/json: schema: type: object properties: error: type: string description: Human-readable error message. '503': description: Service unavailable. Retry with backoff. content: application/json: schema: type: object properties: error: type: string description: Human-readable error message. components: schemas: VerifiedOrder: type: object required: - orderId - visitorId - totalCents - currency - occurredAt properties: orderId: type: string description: Stable identifier, trimmed before validation. minLength: 1 maxLength: 200 visitorId: type: string description: >- SideShift visitor ID captured at checkout. Required for this custom-store endpoint. pattern: ^[a-zA-Z0-9_-]{16,128}$ totalCents: type: integer minimum: 0 maximum: 100000000000 description: Amount in the currency minor unit, despite the Cents suffix. refundedCents: type: integer minimum: 0 maximum: 100000000000 description: >- Cumulative refunded amount, at most totalCents. Never decreases on replay. default: 0 currency: type: string description: Supported uppercase ISO 4217 currency code. example: USD occurredAt: type: string description: >- Original payment time in UTC. Cannot exceed current time by more than five minutes. Keep unchanged on refunds and retries. format: date-time status: type: string description: >- A refunded order requires refundedCents equal to totalCents. Cancellation cannot be undone by replay. enum: - paid - partially_refunded - refunded - cancelled default: paid isSample: type: boolean default: false description: >- Sample orders do not earn commissions or send managed advertising purchases. Once true, cannot be undone by replay. checkoutToken: type: string description: Optional stable checkout correlation token. minLength: 16 maxLength: 200 items: type: array default: [] maxItems: 500 description: Order line items. items: type: object required: - productId - quantity - priceCents properties: productId: type: string description: Stable identifier, trimmed before validation. minLength: 1 maxLength: 200 title: type: string description: Product title. maxLength: 250 quantity: type: integer minimum: 1 maximum: 10000 description: Purchased quantity. priceCents: type: integer minimum: 0 maximum: 100000000000 description: Amount in the currency minor unit, despite the Cents suffix. advertising: type: object additionalProperties: false description: >- Optional context returned by getAdvertisingContextAsync(). This identity differs from the top-level SideShift visitor ID. required: - visitorId - landingUrl - capturedAt properties: visitorId: type: string description: Advertising visitor identity. minLength: 1 maxLength: 64 landingUrl: type: string description: >- Original HTTPS landing URL with click parameters; no fragment or URL credentials. format: uri maxLength: 4096 capturedAt: type: string description: Context capture time in UTC. format: date-time securitySchemes: StoreOrdersKey: type: http scheme: bearer bearerFormat: ss_orders_… description: >- Store-specific secret generated in Website & sales. Never expose in browser code. ````