Skip to content
SoundSyncAudio software platform

API Reference

Checkout API

Route-backed checkout, quote, tax jurisdiction, and embed checkout handoff API reference.

SoundSync

Verified endpoints

These endpoints are route-backed in the current platform.

GET /api/checkout/payment-methods

Read the currently configured checkout payment choices.

Auth
Public request; operation-specific verification still applies
Scope
Configured platform payment methods, without customer or product ownership data.
Returns
200 { methods: { stripe, paypal } }. Provider configuration does not prove that a particular product or subscription is eligible.
Side effects
None.
Request, response and error reference

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "methods": {
      "type": "object",
      "properties": {
        "stripe": {
          "type": "boolean"
        },
        "paypal": {
          "type": "boolean"
        }
      },
      "required": [
        "stripe",
        "paypal"
      ],
      "additionalProperties": true
    },
    "runtime": {
      "type": "object",
      "properties": {
        "environment": {
          "enum": [
            "test",
            "live"
          ]
        },
        "evaluation": {
          "type": "boolean"
        },
        "developerBillingEnabled": {
          "type": "boolean"
        },
        "evaluationOrigin": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri"
        }
      },
      "additionalProperties": true
    },
    "customerSession": {
      "type": "object",
      "properties": {
        "tokenLifetimeSeconds": {
          "type": "integer",
          "minimum": 0
        },
        "refreshSupported": {
          "const": false
        },
        "websiteSessionDefaultSeconds": {
          "type": "integer",
          "minimum": 0
        }
      },
      "additionalProperties": true
    },
    "locationEvidenceOrigin": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri",
      "description": "Public buyer-browser proof issuer; may differ from the API origin."
    }
  },
  "additionalProperties": true,
  "required": [
    "methods"
  ]
}
POST /api/checkout/product

Create Stripe or PayPal managed checkout, or resolve a supported free claim.

Auth
Account Bearer session token
Scope
Product owner, storefront ownership, marketplace attribution, and customer identity are resolved server-side.
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
201 with provider stripe or paypal, checkoutSessionId, url and applicable stripeMode/paypalMode/saleChannel. A supported free claim returns provider manual with freeClaim, claimed, alreadyClaimed, orderId and url; an existing claim returns 200 rather than 201.
Side effects
Records checkout_started analytics, stores checkout session, records abandoned checkout signal, may create free order/entitlement for free claims.
Notes
Follow the returned provider URL. PayPal supports one-time purchases, not subscriptions. Subscription checkout uses Stripe and one subscription product per request. Server pricing, the $9.99 paid floor, account verification, billing eligibility and commerce controls remain authoritative. Never grant access from a browser return alone. 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

Create a server tax/checkout quote for product checkout.

Auth
Optional authentication OR Account Bearer session token
Scope
Use the authentication and resource scope specified for this operation.
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
201 quote with tax, total, jurisdiction, platform/developer allocation and expiry when internal tax checkout is enabled.
Side effects
Creates quote/calculation rows when internal tax engine is active.
Notes
When internal tax checkout is active, checkout session creation requires a valid server quote. 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/tax-jurisdictions

List checkout-supported tax jurisdictions.

Auth
Public request; operation-specific verification still applies
Scope
Use the authentication and resource scope specified for this operation.
Returns
countries[] supported by the internal tax jurisdiction service.
Side effects
Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
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
}
POST /api/embed/storefront/:storeSlug/checkout

Compatibility endpoint for embedded storefront checkout attempts.

Auth
Allowed embed origin/domain; see the frame and operation notes
Scope
Use the authentication and resource scope specified for this operation.
Returns
409 USE_PRODUCT_CHECKOUT_ENDPOINT and checkoutEndpoint /api/checkout/product.
Side effects
None; returns a compatibility response pointing to canonical product checkout.
Notes
Embedded storefront checkout is intentionally handed off to canonical product checkout. 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.

Money source of truth

Product IDs, quantities, promo codes, and customer identity may come from the browser. Prices, discounts, tax, totals, and revenue allocation are resolved and stored server-side.

PayPal approval and completion

Read GET /api/checkout/payment-methods, then select paymentProvider: paypal for an eligible one-time checkout or stripe for card/wallet checkout. Both use the same canonical product checkout endpoint. PayPal is not a subscription payment option.

Open the returned provider URL. The configured PayPal return/cancel routes handle the provider handoff; they are not generic client capture APIs and must not be polled or replayed. Confirm the resulting order and authorized customer access after server reconciliation. Closing the provider page or visiting a success URL is not proof of payment.

Product news and marketing preferences

Purchases and storefront customer signups automatically add customers to the relevant developer marketing list. Account and checkout forms do not require a separate marketing opt-in checkbox. Necessary receipts, security and product-access messages remain separate from marketing campaigns.

Saved unsubscribes, complaints, refusals and suppressions remain protected. Signing in, correcting an email or buying again does not silently erase a saved restriction. Marketing messages include an unsubscribe link. Developers remain responsible for the rules applicable to their promotional messages; automatic enrollment is not evidence of affirmative advertising-measurement consent.

Cart-link URLs are not checkout requests

ss_cart is a storefront URL parameter containing product IDs, not a new API request body, customer token, discount instruction or server reservation. The browser reads the public storefront products, checks eligibility and merges its cart; a link does not collect payment.

Continue through the documented canonical product checkout operation. The server recalculates the current products, offers and tax and applies the usual account and minimum-price requirements.

SoundSync

Build and test the email button

Campaign and cart-link guide

Copy or insert the link and verify the actual destination before sending.