Skip to content
SoundSyncAudio software platform

API reference

Checkout and Cart API

Endpoint reference for checkout session creation, tax quotes, tax jurisdictions, embedded cart display, coupon handling, and checkout handoff.

SoundSync

Checkout and embedded cart endpoints

Checkout recalculates product, promotion, subscription, and tax pricing server-side before payment.

POST /api/checkout/product

Create a checkout session for a product or cart.

Auth
Account Bearer session token
Scope
Product or storefront scoped
Request fields
  • productId: integer
  • quantity: integer
  • items: array
  • promoCode: string
  • taxQuoteId: string
  • quoteId: string
  • locationEvidenceToken: string. Short-lived browser-edge location proof, not a customer token.
  • headlessOrigin: string
  • storefrontSlug: string
  • paymentProvider: stripe | paypal
  • marketingOptIn: boolean
  • marketingOptOut: boolean
  • offerId: string
  • offerVersionId: string
  • priceVersionId: string
Returns
Stripe Checkout URL/session, PayPal approval URL for one-time purchases, or manual free-claim result.
Side effects
Creates checkout session or free claim, records checkout analytics, applies promo rules, and prepares order/entitlement state after payment.
Notes
Configured products use the selected offerId with offerVersionId and priceVersionId from the current catalog. Stale terms require reloading and customer review, not silent substitution. A recurring offer checks out alone with quantity one. One-time carts use one developer and currency. Qualifying coupon and automatic/BOGO promotions enforce the post-discount cart minimum before tax, not a separate minimum on every discounted line; fully free carts require explicit supported free-redemption permission. Custom websites use the verified exact origin, stored callbacks and private website context. Quote/product requests must agree on customer, cart, location and fresh quote. Never substitute server geolocation or treat a browser return as confirmed payment.
Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "productId": {
      "type": "integer",
      "minimum": 1
    },
    "quantity": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "productId": {
            "type": "integer",
            "minimum": 1
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100
          },
          "offerId": {
            "type": "string",
            "format": "uuid"
          },
          "offerVersionId": {
            "type": "string",
            "format": "uuid"
          },
          "priceVersionId": {
            "type": "string",
            "format": "uuid"
          }
        },
        "additionalProperties": true,
        "required": [
          "productId"
        ]
      },
      "maxItems": 100
    },
    "promoCode": {
      "type": "string"
    },
    "taxQuoteId": {
      "type": "string"
    },
    "quoteId": {
      "type": "string"
    },
    "locationEvidenceToken": {
      "type": "string",
      "maxLength": 2048,
      "description": "Short-lived browser-edge location proof, not a customer token."
    },
    "headlessOrigin": {
      "type": "string",
      "format": "uri"
    },
    "storefrontSlug": {
      "type": "string"
    },
    "paymentProvider": {
      "enum": [
        "stripe",
        "paypal"
      ]
    },
    "marketingOptIn": {
      "type": "boolean"
    },
    "marketingOptOut": {
      "type": "boolean"
    },
    "offerId": {
      "type": "string",
      "format": "uuid"
    },
    "offerVersionId": {
      "type": "string",
      "format": "uuid"
    },
    "priceVersionId": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": true,
  "anyOf": [
    {
      "required": [
        "productId"
      ]
    },
    {
      "required": [
        "items"
      ]
    }
  ]
}

HTTP 201 response (application/json)

{
  "type": "object",
  "properties": {
    "provider": {
      "enum": [
        "stripe",
        "paypal",
        "manual"
      ]
    },
    "checkoutSessionId": {
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "orderId": {
      "type": "integer",
      "minimum": 1
    },
    "paypalMode": {
      "type": "string"
    },
    "stripeMode": {
      "type": "string"
    },
    "freeClaim": {
      "type": "boolean"
    },
    "alreadyClaimed": {
      "type": "boolean"
    },
    "claimed": {
      "type": "boolean"
    },
    "checkoutBypassed": {
      "type": "boolean"
    }
  },
  "additionalProperties": true
}

Documented failures: 503.

Operation errors: CHOOSE_OFFER_REQUIRED, OFFER_CHANGED, CHECKOUT_OFFER_REQUIRED, CHECKOUT_OFFER_VERSION_CONFLICT, SUBSCRIPTION_CART_UNSUPPORTED.

POST /api/checkout/quote

Quote checkout tax and totals before checkout.

Auth
Optional authentication OR Account Bearer session token
Scope
Product or storefront scoped
Request fields
  • productId: integer
  • items: array
  • countryCode: string
  • regionCode: string
  • postalCode: string
  • promoCode: string
  • headlessOrigin: string
  • storefrontSlug: string
  • locationEvidenceToken: string. Short-lived browser-edge location proof, not a customer token.
  • offerId: string
  • offerVersionId: string
  • priceVersionId: string
  • quoteId: string
Returns
Quote payload with pricing/tax details used by checkout.
Notes
Configured products use the selected offerId with offerVersionId and priceVersionId from the current catalog. Stale terms require reloading and customer review, not silent substitution. A recurring offer checks out alone with quantity one. One-time carts use one developer and currency. Qualifying coupon and automatic/BOGO promotions enforce the post-discount cart minimum before tax, not a separate minimum on every discounted line; fully free carts require explicit supported free-redemption permission. Custom websites use the verified exact origin, stored callbacks and private website context. Quote/product requests must agree on customer, cart, location and fresh quote. Never substitute server geolocation or treat a browser return as confirmed payment.
Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "productId": {
      "type": "integer",
      "minimum": 1
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "productId": {
            "type": "integer",
            "minimum": 1
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100
          },
          "offerId": {
            "type": "string",
            "format": "uuid"
          },
          "offerVersionId": {
            "type": "string",
            "format": "uuid"
          },
          "priceVersionId": {
            "type": "string",
            "format": "uuid"
          }
        },
        "additionalProperties": true,
        "required": [
          "productId"
        ]
      },
      "maxItems": 100
    },
    "countryCode": {
      "type": "string"
    },
    "regionCode": {
      "type": "string"
    },
    "postalCode": {
      "type": "string"
    },
    "promoCode": {
      "type": "string"
    },
    "headlessOrigin": {
      "type": "string",
      "format": "uri"
    },
    "storefrontSlug": {
      "type": "string"
    },
    "locationEvidenceToken": {
      "type": "string",
      "maxLength": 2048,
      "description": "Short-lived browser-edge location proof, not a customer token."
    },
    "offerId": {
      "type": "string",
      "format": "uuid"
    },
    "offerVersionId": {
      "type": "string",
      "format": "uuid"
    },
    "priceVersionId": {
      "type": "string",
      "format": "uuid"
    },
    "quoteId": {
      "type": "string"
    }
  },
  "additionalProperties": true
}

HTTP 201 response (application/json)

{
  "type": "object",
  "properties": {
    "quote": {
      "type": "object",
      "properties": {
        "quoteId": {
          "type": "string"
        },
        "currency": {
          "type": "string"
        },
        "subtotalCents": {
          "type": "integer",
          "minimum": 0
        },
        "taxAmountCents": {
          "type": "integer",
          "minimum": 0
        },
        "totalCents": {
          "type": "integer",
          "minimum": 0
        },
        "supported": {
          "type": "boolean"
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}

Documented failures: 503.

Operation errors: CHOOSE_OFFER_REQUIRED, OFFER_CHANGED, CHECKOUT_OFFER_REQUIRED, CHECKOUT_OFFER_VERSION_CONFLICT, SUBSCRIPTION_CART_UNSUPPORTED.

GET /api/checkout/location-evidence

Obtain short-lived, edge-observed buyer location evidence for custom website quoting.

Auth
Public request; operation-specific verification still applies
Scope
Origin/storefront-bound edge-observed location proof, not account authorization.
Request fields
  • query headlessOrigin: string (required)
  • query storefrontSlug: string (required)
Returns
An opaque evidence token and expiresAt, or 503 if the edge adapter is not configured.
Notes
Call directly from the buyer browser using credentials: omit. Cloudflare signs its observed country and a visitor-IP hash for this origin/storefront, valid for five minutes. Pass evidence in the quote body. Your private platform forwards the actual visitor IP with its verified website key; the platform validates the signature and context. It never grants account, payment or tax-setting permissions. SoundSync must route this endpoint through its edge adapter; do not give signing secrets to developers. Fetch directly from the buyer browser using credentials:omit and Origin matching headlessOrigin. Discover the separate public issuer via payment-methods.locationEvidenceOrigin; do not assume the API origin serves the edge adapter. The five-minute proof binds observed country and visitor-IP hash. Forward as locationEvidenceToken through your private website platform with genuine visitor-IP context. A website key cannot sign this proof. Missing configured edge support returns 503; do not bypass tax evidence checks.
Request, response and error reference

Query and header parameters

[
  {
    "name": "headlessOrigin",
    "in": "query",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "storefrontSlug",
    "in": "query",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

No request body fields are read by this operation.

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "evidence": {
      "type": "string"
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time"
    }
  },
  "additionalProperties": true,
  "required": [
    "evidence",
    "expiresAt"
  ]
}

Documented failures: 400, 401, 403, 404, 409, 500, 503.

GET /api/checkout/tax-jurisdictions

List tax jurisdictions available to checkout quoting.

Auth
Public request; operation-specific verification still applies
Scope
Product or storefront scoped
Returns
Country/jurisdiction list used by checkout tax UI.
Request, response and error reference

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "countries": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "countryCode": {
            "type": "string"
          },
          "countryName": {
            "type": "string"
          },
          "regions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "regionCode": {
                  "type": "string"
                },
                "regionName": {
                  "type": "string"
                }
              },
              "additionalProperties": true
            }
          }
        },
        "additionalProperties": true
      }
    }
  },
  "additionalProperties": true
}
GET /api/checkout/status

Read confirmed checkout/fulfillment status for the purchasing customer.

Auth
Account Bearer session token
Scope
Verified purchasing customer, matching storefront and platform payment environment.
Request fields
  • query sessionId: string (required)
  • query storefrontSlug: string (required)
Returns
Status, fulfilled flag, provider, currency, totalCents and taxAmountCents. Current library entitlements determine present access.
Notes
Read-only; never captures payment or grants a license. Buyer, storefront and platform payment environment must match. Read-only: never captures payment, creates access or pays earnings. A success URL is not payment proof. Current library entitlements determine access after a refund or revocation.
Request, response and error reference

Query and header parameters

[
  {
    "name": "sessionId",
    "in": "query",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "storefrontSlug",
    "in": "query",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

No request body fields are read by this operation.

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "fulfilled": {
      "type": "boolean"
    },
    "provider": {
      "type": "string",
      "enum": [
        "stripe",
        "paypal"
      ]
    },
    "currency": {
      "type": "string"
    },
    "totalCents": {
      "type": [
        "integer",
        "null"
      ]
    },
    "taxAmountCents": {
      "type": [
        "integer",
        "null"
      ]
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 404, 409, 500, 503.

POST /api/checkout/external

Open the saved FastSpring, Gumroad or WooCommerce product checkout.

Auth
Account Bearer session token
Scope
Verified customer session and independently verified website; one active allowed product/provider/environment mapping.
Request fields
  • provider: fastspring | gumroad | woocommerce (required)
  • productId: integer (required)
  • storefrontSlug: string (required)
  • headlessOrigin: string (required)
  • externalEnvironment: test | live
Returns
Saved allowlisted external URL and paymentFlow: external.
Notes
External licensing, not Full Store. Choose externalEnvironment test/live independently of Stripe settings. An active mapping, verified website and owned available serial product are required. This redirect never grants a license or credits SoundSync payouts. Full Store uses the managed quote/product checkout routes instead. External licensing, not Full Store. externalEnvironment defaults to live and is independent of Stripe/PayPal environment. Opens only the saved allowed URL. It never calculates SoundSync tax, captures/confirms payment or grants a license. A provider return URL is not SoundSync checkout-status confirmation.
Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "fastspring",
        "gumroad",
        "woocommerce"
      ]
    },
    "productId": {
      "type": "integer",
      "minimum": 1
    },
    "storefrontSlug": {
      "type": "string"
    },
    "headlessOrigin": {
      "type": "string"
    },
    "externalEnvironment": {
      "type": "string",
      "enum": [
        "test",
        "live"
      ]
    }
  },
  "additionalProperties": true,
  "required": [
    "provider",
    "productId",
    "storefrontSlug",
    "headlessOrigin"
  ]
}

HTTP 201 response (application/json)

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "provider": {
      "type": "string"
    },
    "paymentFlow": {
      "const": "external"
    },
    "message": {
      "type": "string"
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 404, 409, 500, 503.

POST /api/embed/storefront/:storeSlug/cart

Accept client-side cart state for embedded storefront display.

Auth
Allowed embed origin/domain; see the frame and operation notes
Scope
Product or storefront scoped
Request fields
  • items: array
Returns
Accepted cart echo plus checkout endpoint. Checkout recalculates server-side.
Notes
An echo for client cart display, not a priced or authorized server cart. Use /api/checkout/product for current checkout creation.
Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "productId": {
            "type": "integer",
            "minimum": 1
          },
          "quantity": {
            "type": "integer",
            "minimum": 1
          }
        },
        "additionalProperties": true
      }
    }
  },
  "additionalProperties": true
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "cart": {
      "type": "object",
      "properties": {
        "items": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true,
            "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
          }
        },
        "serverCalculated": {
          "const": false
        }
      },
      "additionalProperties": true
    },
    "checkoutEndpoint": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 500.

POST /api/embed/storefront/:storeSlug/cart/items

Accept one embedded cart item for display.

Auth
Allowed embed origin/domain; see the frame and operation notes
Scope
Product or storefront scoped
Request fields
  • productId: integer
  • quantity: integer
Returns
Accepted item echo plus checkout endpoint.
Notes
Echoes the body for display; does not reserve inventory, validate totals or start payment.
Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "productId": {
      "type": "integer",
      "minimum": 1
    },
    "quantity": {
      "type": "integer",
      "minimum": 1
    }
  },
  "additionalProperties": true
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "item": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    },
    "checkoutEndpoint": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 500.

POST /api/embed/storefront/:storeSlug/cart/coupon

Attach a coupon/promo code to embedded cart display.

Auth
Allowed embed origin/domain; see the frame and operation notes
Scope
Product or storefront scoped
Request fields
  • code: string
  • coupon: string
Returns
Coupon echo. Final validation happens during server-side checkout.
Notes
Echoes code or coupon only. Final validation occurs during checkout; a successful echo is not a valid discount.
Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "coupon": {
      "type": "string"
    }
  },
  "additionalProperties": true
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "coupon": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 500.

POST /api/embed/storefront/:storeSlug/checkout

Embedded checkout handoff route.

Auth
Allowed embed origin/domain; see the frame and operation notes
Scope
Product or storefront scoped
Returns
409 response pointing clients to /api/checkout/product.
Side effects
None; returns a compatibility response pointing to canonical product checkout.
Notes
This endpoint exists to keep embedded clients on the canonical checkout creation route. Compatibility endpoint; does not create checkout. Send authenticated checkout requests to /api/checkout/product.
Request, response and error reference

No request body fields are read by this operation.

HTTP 409 response (application/json)

{
  "type": "object",
  "properties": {
    "code": {
      "const": "USE_PRODUCT_CHECKOUT_ENDPOINT"
    },
    "message": {
      "type": "string"
    },
    "checkoutEndpoint": {
      "const": "/api/checkout/product"
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 500.

SoundSync

Checkout payload fields

The checkout endpoint accepts single-product and cart payloads.

FieldUse
productIdSingle-product checkout.
items, cartItems, or lineItemsCart checkout with product ids and quantities.
customerEmail/customerNameCustomer identity fields when supplied before payment.
promoCode/couponPromotion code to validate during checkout.
storefrontSlug and saleChannelAttribution and storefront/customer path context.
successUrl and cancelUrlHosted return routes remain validated and canonicalized. For an external frontend, use a verified website configuration.
headlessOrigin + storefrontSlug + quoteIdApproved external website checkout. SoundSync uses the saved callback paths and validates the server quote against buyer, cart, location and environment.

SoundSync

Custom websites with any framework

Use our HTTPS/JSON APIs from your own platform in any language. Keep your existing frontend and hosting while SoundSync manages customer accounts, tax, checkout, licensing and delivery.

StepImplementation
Connect your websiteIn Developer → Brand Domain → External website, save the HTTPS origin, copy the private server connection key, add the TXT ownership record and verify. Keep your current hosting records.
Choose your implementationCall the documented HTTP APIs directly using your platform language. The Astro / Node starter in External website settings is an optional shortcut, not an API requirement. See Custom Website API for the framework-neutral flow.
Customer accountsUse account APIs through your own platform. Keep tokens in server-side sessions. Verified external callbacks support email verification and password recovery on your site. POST verification can return JSON when Accept is application/json.
Tax and paymentRender country/region choices from tax-jurisdictions, show a server quote and redirect to SoundSync-managed Stripe or PayPal checkout. SoundSync remains the merchant. Subscriptions use Stripe.
Confirmation and deliveryGET /api/checkout/status?sessionId=...&storefrontSlug=... requires the purchasing customer session. Only confirmed fulfillment grants access; current library entitlements authorize direct signed R2 downloads.
Fees and payoutsUse the current pricing and legal pages. Accounting and actual provider-fee deductions remain centralized in SoundSync; the connector does not calculate developer fees or send payouts.

SoundSync

Custom website checkout

Custom Website API

Verified origins, callbacks, buyer evidence and purchasing-customer status.

External licensing

Provider checkout redirects are not managed payment confirmation.