Skip to content
SoundSyncAudio software platform

API reference

Purchase Options API

Product purchase choices, immutable price and terms versions, scoped deal schedules and checkout selection.

Keep accepted terms intact

New purchase-option prices and fixed-amount deals use USD only. The editor shows a fixed USD field, not a currency choice, and the API rejects unsupported currencies before saving new terms. If an older record uses another currency, enter a new USD amount explicitly; historical prices, receipts and accepted subscriber terms are not converted or relabeled.

Offer terms and prices are versioned. Editing the next offer does not rewrite a customer's accepted purchase snapshot. Use the current offer, offer-version and price-version identifiers at checkout. If terms changed, reload and let the customer review them; do not silently substitute a different offer.

A recurring offer checks out on its own with quantity one. One-time carts stay within one developer and currency. Catalog visibility, storefront visibility, marketplace visibility, publication and existing ownership are separate controls.

For a plan that awards lasting product ownership as invoices are paid, use the ownership subscription-bundle workflow. The new purchase-options editor does not publish keep-products bundles. Access-only subscriptions and earned ownership must not be described as the same thing.

SoundSync

Automatic protected collections

ChoiceWhat is included
Root product onlyThe root product is included automatically. Do not add its ID to includedProductIds or excludedProductIds.
Selected productsSelect at least one additional product owned by this workspace. Included and excluded lists cannot overlap or create a circular collection.
Linked expansionsAutomatic membership uses eligible protected content linked to this instrument, with a published release and recorded availability.
Developer catalogAutomatic membership uses eligible published protected-content identities in this workspace, not every ordinary product listing.
Include future contentAvailable only for recurring linked-expansion or developer-catalog choices. Content must meet the same publication and inclusion requirements when it becomes available.
Fixed current collectionKeep the saved membership unless you deliberately refresh it. A price edit does not silently add new content; later hiding of a listing is not a command to withdraw already granted access.

SoundSync

Purchase configuration and deals

GET /api/products/purchase-options/capabilities

Read purchase-option and protected-content availability

Auth
Account Bearer session token
Scope
products.view; effective developer workspace and its applicable product scope.
Returns
HTTP 200: enabled, checkoutReady, modes, protectedContentEnabled, subscriptionDealDurations, minimumPurchaseMinor.
Notes
Read the permitted product configuration.
Request, response and error reference

No request body fields are read by this operation.

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean"
    },
    "checkoutReady": {
      "type": "boolean"
    },
    "modes": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "one_time",
          "subscription",
          "both"
        ]
      }
    },
    "protectedContentEnabled": {
      "type": "boolean"
    },
    "subscriptionDealDurations": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "minimumPurchaseMinor": {
      "type": "integer",
      "minimum": 0
    }
  },
  "additionalProperties": true
}

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

GET /api/products/{id}/purchase-options

Read saved offers, deal history and migration review

Auth
Account Bearer session token
Scope
products.view; product ownership and assigned-product access in the effective workspace.
Returns
HTTP 200: productId, offers, deals, editorOffers, protectedContentEnabled, migrationReview, migrationNotes.
Notes
Configure one or two distinct kinds on one product. New prices and fixed-amount deals require USD; unsupported currencies return 400 PURCHASE_OFFER_CURRENCY_UNSUPPORTED with field:currency. Existing recorded currencies are not converted or relabeled. New immutable terms/price versions do not rewrite previously accepted customer snapshots. Supply expectedVersionId when editing to detect stale state. Published offers need a published product, price and ready checkout. Versioned subscription prices use day, week, month or year with intervalCount from 1 to 365, subject to provider limits. Dedicated legacy subscription bundles retain their own monthly/yearly contract. Published subscriptions use fourteen-day payment recovery and cancellation through the paid period. keep_products publication belongs to the existing ownership subscription-bundle workflow; this editor returns OWNERSHIP_SUBSCRIPTION_BUNDLE_REQUIRED. Future inclusion is limited to recurring linked_expansions/developer_catalog rules. Product ownership spans that product releases; technical content compatibility remains separate. Read the permitted product configuration.
Request, response and error reference

No request body fields are read by this operation.

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "productId": {
      "type": "integer",
      "minimum": 1
    },
    "offers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "productId": {
            "type": "integer",
            "minimum": 1
          },
          "developerId": {
            "type": "integer",
            "minimum": 1
          },
          "kind": {
            "type": "string",
            "enum": [
              "one_time",
              "subscription"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "published",
              "retired"
            ]
          },
          "versionId": {
            "type": "string",
            "format": "uuid"
          },
          "version": {
            "type": "integer",
            "minimum": 1
          },
          "price": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "amountMinor": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Integer minor units, not a floating-dollar amount."
                  },
                  "currency": {
                    "type": "string",
                    "description": "New prices use usd. Reads retain the currency recorded on historical versions without conversion."
                  },
                  "billingInterval": {
                    "anyOf": [
                      {
                        "type": "string",
                        "enum": [
                          "day",
                          "week",
                          "month",
                          "year"
                        ]
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "intervalCount": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 365
                  },
                  "renewalPolicy": {
                    "type": "string",
                    "enum": [
                      "not_recurring",
                      "locked",
                      "current_list_v1"
                    ]
                  }
                },
                "additionalProperties": true
              },
              {
                "type": "null"
              }
            ]
          },
          "fulfillmentMode": {
            "type": "string",
            "enum": [
              "permanent",
              "access",
              "keep_products"
            ]
          },
          "inclusionScope": {
            "type": "string",
            "enum": [
              "root_only",
              "selected_products",
              "linked_expansions",
              "developer_catalog"
            ]
          },
          "includeFuture": {
            "type": "boolean"
          },
          "includedProductIds": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 1
            }
          },
          "excludedProductIds": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 1
            }
          },
          "terms": {
            "type": "object",
            "properties": {
              "updatePolicy": {
                "type": "string",
                "enum": [
                  "existing_policy",
                  "current_major",
                  "all_versions"
                ],
                "description": "Older values are accepted but new saved terms normalize to all_versions. Product ownership is not a paid-major gate."
              },
              "offlinePolicy": {
                "type": "string",
                "enum": [
                  "existing_policy",
                  "permanent_device",
                  "grace",
                  "online_only"
                ]
              },
              "contentProtection": {
                "type": "string",
                "enum": [
                  "protected",
                  "download_only",
                  "none"
                ]
              },
              "trialScope": {
                "type": "string",
                "enum": [
                  "root_only",
                  "offer_contents"
                ]
              },
              "trialDays": {
                "type": "integer",
                "enum": [
                  0,
                  7,
                  14,
                  30
                ]
              },
              "failedPaymentGraceDays": {
                "type": "integer",
                "enum": [
                  0,
                  3,
                  7,
                  14
                ]
              },
              "cancellationBehavior": {
                "type": "string",
                "enum": [
                  "access_until_period_end",
                  "lock_immediately"
                ]
              }
            },
            "additionalProperties": true
          },
          "membershipPreview": {
            "type": "object",
            "properties": {},
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      }
    },
    "deals": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    },
    "editorOffers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "productId": {
            "type": "integer",
            "minimum": 1
          },
          "developerId": {
            "type": "integer",
            "minimum": 1
          },
          "kind": {
            "type": "string",
            "enum": [
              "one_time",
              "subscription"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "published",
              "retired"
            ]
          },
          "versionId": {
            "type": "string",
            "format": "uuid"
          },
          "version": {
            "type": "integer",
            "minimum": 1
          },
          "price": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "amountMinor": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Integer minor units, not a floating-dollar amount."
                  },
                  "currency": {
                    "type": "string",
                    "description": "New prices use usd. Reads retain the currency recorded on historical versions without conversion."
                  },
                  "billingInterval": {
                    "anyOf": [
                      {
                        "type": "string",
                        "enum": [
                          "day",
                          "week",
                          "month",
                          "year"
                        ]
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "intervalCount": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 365
                  },
                  "renewalPolicy": {
                    "type": "string",
                    "enum": [
                      "not_recurring",
                      "locked",
                      "current_list_v1"
                    ]
                  }
                },
                "additionalProperties": true
              },
              {
                "type": "null"
              }
            ]
          },
          "fulfillmentMode": {
            "type": "string",
            "enum": [
              "permanent",
              "access",
              "keep_products"
            ]
          },
          "inclusionScope": {
            "type": "string",
            "enum": [
              "root_only",
              "selected_products",
              "linked_expansions",
              "developer_catalog"
            ]
          },
          "includeFuture": {
            "type": "boolean"
          },
          "includedProductIds": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 1
            }
          },
          "excludedProductIds": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 1
            }
          },
          "terms": {
            "type": "object",
            "properties": {
              "updatePolicy": {
                "type": "string",
                "enum": [
                  "existing_policy",
                  "current_major",
                  "all_versions"
                ],
                "description": "Older values are accepted but new saved terms normalize to all_versions. Product ownership is not a paid-major gate."
              },
              "offlinePolicy": {
                "type": "string",
                "enum": [
                  "existing_policy",
                  "permanent_device",
                  "grace",
                  "online_only"
                ]
              },
              "contentProtection": {
                "type": "string",
                "enum": [
                  "protected",
                  "download_only",
                  "none"
                ]
              },
              "trialScope": {
                "type": "string",
                "enum": [
                  "root_only",
                  "offer_contents"
                ]
              },
              "trialDays": {
                "type": "integer",
                "enum": [
                  0,
                  7,
                  14,
                  30
                ]
              },
              "failedPaymentGraceDays": {
                "type": "integer",
                "enum": [
                  0,
                  3,
                  7,
                  14
                ]
              },
              "cancellationBehavior": {
                "type": "string",
                "enum": [
                  "access_until_period_end",
                  "lock_immediately"
                ]
              }
            },
            "additionalProperties": true
          },
          "membershipPreview": {
            "type": "object",
            "properties": {},
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      }
    },
    "protectedContentEnabled": {
      "type": "boolean"
    },
    "migrationReview": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "migrationNotes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "additionalProperties": true
}

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

PUT /api/products/{id}/purchase-options

Save selected purchase options and related deal changes

Auth
Account Bearer session token
Scope
products.edit; product ownership and assigned-product access in the effective workspace.
Request fields
  • offers: array (required)
  • deals: array
  • retireOfferIds: array
Returns
HTTP 200: offers, deals.
Notes
Configure one or two distinct kinds on one product. New prices and fixed-amount deals require USD; unsupported currencies return 400 PURCHASE_OFFER_CURRENCY_UNSUPPORTED with field:currency. Existing recorded currencies are not converted or relabeled. New immutable terms/price versions do not rewrite previously accepted customer snapshots. Supply expectedVersionId when editing to detect stale state. Published offers need a published product, price and ready checkout. Versioned subscription prices use day, week, month or year with intervalCount from 1 to 365, subject to provider limits. Dedicated legacy subscription bundles retain their own monthly/yearly contract. Published subscriptions use fourteen-day payment recovery and cancellation through the paid period. keep_products publication belongs to the existing ownership subscription-bundle workflow; this editor returns OWNERSHIP_SUBSCRIPTION_BUNDLE_REQUIRED. Future inclusion is limited to recurring linked_expansions/developer_catalog rules. Product ownership spans that product releases; technical content compatibility remains separate. Omitted kinds are not retired. Supply explicit retireOfferIds or use the retirement route. Every deals entry needs promotion or retirePromotionId for a kind included in this save. If both are supplied, retirement takes precedence. Automatic linked-expansion/catalog membership uses eligible published protected-content identities, not every ordinary listing. monthly/yearly price inputs normalize to month/year. Edit the permitted product without granting publication or archive authority.
Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "offers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "productId": {
            "type": "integer",
            "minimum": 1
          },
          "developerId": {
            "type": "integer",
            "minimum": 1
          },
          "kind": {
            "type": "string",
            "enum": [
              "one_time",
              "subscription"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "published"
            ]
          },
          "versionId": {
            "type": "string",
            "format": "uuid"
          },
          "version": {
            "type": "integer",
            "minimum": 1
          },
          "price": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "amountMinor": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  "currency": {
                    "type": "string",
                    "pattern": "^[uU][sS][dD]$",
                    "description": "USD only. New price currency defaults to usd when omitted; no currency conversion is performed."
                  },
                  "billingInterval": {
                    "anyOf": [
                      {
                        "type": "string",
                        "enum": [
                          "day",
                          "week",
                          "month",
                          "year",
                          "monthly",
                          "yearly"
                        ],
                        "description": "Use day, week, month or year with intervalCount. monthly/yearly input aliases normalize to month/year; saved daily and weekly cadences remain day/week. Provider limits still apply."
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "intervalCount": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 365
                  },
                  "renewalPolicy": {
                    "type": "string",
                    "enum": [
                      "not_recurring",
                      "locked",
                      "current_list_v1"
                    ]
                  }
                },
                "additionalProperties": true,
                "required": [
                  "amountMinor"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "fulfillmentMode": {
            "type": "string",
            "enum": [
              "permanent",
              "access",
              "keep_products"
            ]
          },
          "inclusionScope": {
            "type": "string",
            "enum": [
              "root_only",
              "selected_products",
              "linked_expansions",
              "developer_catalog"
            ]
          },
          "includeFuture": {
            "type": "boolean"
          },
          "includedProductIds": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 1
            },
            "maxItems": 10000,
            "uniqueItems": true
          },
          "excludedProductIds": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 1
            },
            "maxItems": 10000,
            "uniqueItems": true
          },
          "terms": {
            "type": "object",
            "properties": {
              "updatePolicy": {
                "type": "string",
                "enum": [
                  "existing_policy",
                  "current_major",
                  "all_versions"
                ],
                "description": "Older values are accepted but new saved terms normalize to all_versions. Product ownership is not a paid-major gate."
              },
              "offlinePolicy": {
                "type": "string",
                "enum": [
                  "existing_policy",
                  "permanent_device",
                  "grace",
                  "online_only"
                ]
              },
              "contentProtection": {
                "type": "string",
                "enum": [
                  "protected",
                  "download_only",
                  "none"
                ]
              },
              "trialScope": {
                "type": "string",
                "enum": [
                  "root_only",
                  "offer_contents"
                ]
              },
              "trialDays": {
                "type": "integer",
                "enum": [
                  0,
                  7,
                  14,
                  30
                ]
              },
              "failedPaymentGraceDays": {
                "type": "integer",
                "enum": [
                  0,
                  3,
                  7,
                  14
                ]
              },
              "cancellationBehavior": {
                "type": "string",
                "enum": [
                  "access_until_period_end",
                  "lock_immediately"
                ]
              }
            },
            "additionalProperties": true
          },
          "membershipPreview": {
            "type": "object",
            "properties": {},
            "additionalProperties": true
          },
          "expectedVersionId": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ]
          },
          "refreshCurrentCollection": {
            "type": "boolean"
          }
        },
        "additionalProperties": true,
        "required": [
          "kind"
        ],
        "allOf": [
          {
            "if": {
              "properties": {
                "includeFuture": {
                  "const": true
                }
              },
              "required": [
                "includeFuture"
              ]
            },
            "then": {
              "properties": {
                "kind": {
                  "const": "subscription"
                },
                "inclusionScope": {
                  "type": "string",
                  "enum": [
                    "linked_expansions",
                    "developer_catalog"
                  ]
                }
              },
              "required": [
                "inclusionScope"
              ]
            }
          },
          {
            "if": {
              "anyOf": [
                {
                  "not": {
                    "required": [
                      "inclusionScope"
                    ]
                  }
                },
                {
                  "properties": {
                    "inclusionScope": {
                      "const": "root_only"
                    }
                  },
                  "required": [
                    "inclusionScope"
                  ]
                }
              ]
            },
            "then": {
              "properties": {
                "includedProductIds": {
                  "maxItems": 0
                },
                "excludedProductIds": {
                  "maxItems": 0
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "kind": {
                  "const": "one_time"
                }
              },
              "required": [
                "kind"
              ]
            },
            "then": {
              "properties": {
                "fulfillmentMode": {
                  "const": "permanent"
                },
                "price": {
                  "anyOf": [
                    {
                      "type": "null"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "billingInterval": {
                          "type": "null"
                        },
                        "intervalCount": {
                          "const": 1
                        },
                        "renewalPolicy": {
                          "const": "not_recurring"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "kind": {
                  "const": "subscription"
                }
              },
              "required": [
                "kind"
              ]
            },
            "then": {
              "properties": {
                "fulfillmentMode": {
                  "type": "string",
                  "enum": [
                    "access",
                    "keep_products"
                  ]
                },
                "terms": {
                  "properties": {
                    "offlinePolicy": {
                      "type": "string",
                      "enum": [
                        "existing_policy",
                        "grace",
                        "online_only"
                      ]
                    }
                  }
                },
                "price": {
                  "anyOf": [
                    {
                      "type": "null"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "amountMinor": {
                          "minimum": 1
                        },
                        "billingInterval": {
                          "type": "string",
                          "enum": [
                            "day",
                            "week",
                            "month",
                            "year",
                            "monthly",
                            "yearly"
                          ]
                        },
                        "renewalPolicy": {
                          "type": "string",
                          "enum": [
                            "locked",
                            "current_list_v1"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "inclusionScope": {
                  "const": "selected_products"
                }
              },
              "required": [
                "inclusionScope"
              ]
            },
            "then": {
              "properties": {
                "includedProductIds": {
                  "minItems": 1
                }
              },
              "required": [
                "includedProductIds"
              ]
            }
          },
          {
            "if": {
              "properties": {
                "status": {
                  "const": "published"
                }
              },
              "required": [
                "status"
              ]
            },
            "then": {
              "properties": {
                "price": {
                  "type": "object"
                }
              },
              "required": [
                "price"
              ]
            }
          },
          {
            "if": {
              "properties": {
                "kind": {
                  "const": "subscription"
                },
                "status": {
                  "const": "published"
                }
              },
              "required": [
                "kind",
                "status"
              ]
            },
            "then": {
              "properties": {
                "fulfillmentMode": {
                  "const": "access"
                },
                "terms": {
                  "properties": {
                    "failedPaymentGraceDays": {
                      "const": 14
                    },
                    "cancellationBehavior": {
                      "const": "access_until_period_end"
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "minItems": 1,
      "maxItems": 2,
      "allOf": [
        {
          "contains": {
            "properties": {
              "kind": {
                "const": "one_time"
              }
            },
            "required": [
              "kind"
            ]
          },
          "minContains": 0,
          "maxContains": 1
        },
        {
          "contains": {
            "properties": {
              "kind": {
                "const": "subscription"
              }
            },
            "required": [
              "kind"
            ]
          },
          "minContains": 0,
          "maxContains": 1
        }
      ]
    },
    "deals": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "one_time",
              "subscription"
            ]
          },
          "promotion": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "offerId": {
                "type": "string",
                "format": "uuid"
              },
              "campaignId": {
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": 1
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "status": {
                "type": "string",
                "enum": [
                  "active",
                  "retired"
                ]
              },
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200,
                "pattern": "\\S"
              },
              "discountType": {
                "type": "string",
                "enum": [
                  "percent_bps",
                  "amount_minor"
                ]
              },
              "discountValue": {
                "type": "integer",
                "minimum": 1,
                "maximum": 9007199254740991
              },
              "currency": {
                "anyOf": [
                  {
                    "type": "string",
                    "pattern": "^[uU][sS][dD]$",
                    "description": "USD only. New price currency defaults to usd when omitted; no currency conversion is performed."
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "duration": {
                "type": "string",
                "enum": [
                  "first_period",
                  "limited_periods",
                  "ongoing"
                ]
              },
              "durationPeriods": {
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1200
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "startsAt": {
                "type": "string",
                "format": "date-time"
              },
              "endsAt": {
                "anyOf": [
                  {
                    "type": "string",
                    "format": "date-time"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "couponCode": {
                "anyOf": [
                  {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9_-]{0,64}$"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "stackingPolicy": {
                "type": "string",
                "enum": [
                  "exclusive",
                  "with_sale"
                ]
              },
              "eligibility": {
                "type": "object",
                "properties": {
                  "newCustomersOnly": {
                    "type": "boolean"
                  },
                  "returningCustomersAllowed": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              },
              "replacesPromotionId": {
                "type": "string",
                "format": "uuid"
              }
            },
            "additionalProperties": true,
            "required": [
              "title",
              "discountType",
              "discountValue",
              "startsAt"
            ],
            "allOf": [
              {
                "if": {
                  "properties": {
                    "discountType": {
                      "const": "amount_minor"
                    }
                  },
                  "required": [
                    "discountType"
                  ]
                },
                "then": {
                  "properties": {
                    "currency": {
                      "type": "string",
                      "pattern": "^[uU][sS][dD]$",
                      "description": "USD only. New price currency defaults to usd when omitted; no currency conversion is performed."
                    }
                  },
                  "required": [
                    "currency"
                  ]
                }
              },
              {
                "if": {
                  "properties": {
                    "discountType": {
                      "const": "percent_bps"
                    }
                  },
                  "required": [
                    "discountType"
                  ]
                },
                "then": {
                  "properties": {
                    "discountValue": {
                      "maximum": 10000
                    }
                  }
                }
              },
              {
                "if": {
                  "properties": {
                    "duration": {
                      "const": "limited_periods"
                    }
                  },
                  "required": [
                    "duration"
                  ]
                },
                "then": {
                  "properties": {
                    "durationPeriods": {
                      "type": "integer",
                      "minimum": 1,
                      "maximum": 1200
                    }
                  },
                  "required": [
                    "durationPeriods"
                  ]
                }
              },
              {
                "if": {
                  "properties": {
                    "duration": {
                      "const": "ongoing"
                    }
                  },
                  "required": [
                    "duration"
                  ]
                },
                "then": {
                  "properties": {
                    "durationPeriods": {
                      "type": "null"
                    }
                  }
                }
              },
              {
                "if": {
                  "anyOf": [
                    {
                      "not": {
                        "required": [
                          "duration"
                        ]
                      }
                    },
                    {
                      "properties": {
                        "duration": {
                          "const": "first_period"
                        }
                      },
                      "required": [
                        "duration"
                      ]
                    }
                  ]
                },
                "then": {
                  "properties": {
                    "durationPeriods": {
                      "anyOf": [
                        {
                          "const": 1
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  }
                }
              }
            ]
          },
          "retirePromotionId": {
            "type": "string",
            "format": "uuid"
          }
        },
        "additionalProperties": true,
        "required": [
          "kind"
        ],
        "anyOf": [
          {
            "required": [
              "promotion"
            ]
          },
          {
            "required": [
              "retirePromotionId"
            ]
          }
        ],
        "allOf": [
          {
            "if": {
              "properties": {
                "kind": {
                  "const": "one_time"
                }
              },
              "required": [
                "kind"
              ]
            },
            "then": {
              "properties": {
                "promotion": {
                  "properties": {
                    "duration": {
                      "const": "first_period"
                    },
                    "durationPeriods": {
                      "anyOf": [
                        {
                          "const": 1
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        ]
      }
    },
    "retireOfferIds": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "maxItems": 2
    }
  },
  "additionalProperties": true,
  "required": [
    "offers"
  ]
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "offers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "productId": {
            "type": "integer",
            "minimum": 1
          },
          "developerId": {
            "type": "integer",
            "minimum": 1
          },
          "kind": {
            "type": "string",
            "enum": [
              "one_time",
              "subscription"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "published",
              "retired"
            ]
          },
          "versionId": {
            "type": "string",
            "format": "uuid"
          },
          "version": {
            "type": "integer",
            "minimum": 1
          },
          "price": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "amountMinor": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Integer minor units, not a floating-dollar amount."
                  },
                  "currency": {
                    "type": "string",
                    "description": "New prices use usd. Reads retain the currency recorded on historical versions without conversion."
                  },
                  "billingInterval": {
                    "anyOf": [
                      {
                        "type": "string",
                        "enum": [
                          "day",
                          "week",
                          "month",
                          "year"
                        ]
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "intervalCount": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 365
                  },
                  "renewalPolicy": {
                    "type": "string",
                    "enum": [
                      "not_recurring",
                      "locked",
                      "current_list_v1"
                    ]
                  }
                },
                "additionalProperties": true
              },
              {
                "type": "null"
              }
            ]
          },
          "fulfillmentMode": {
            "type": "string",
            "enum": [
              "permanent",
              "access",
              "keep_products"
            ]
          },
          "inclusionScope": {
            "type": "string",
            "enum": [
              "root_only",
              "selected_products",
              "linked_expansions",
              "developer_catalog"
            ]
          },
          "includeFuture": {
            "type": "boolean"
          },
          "includedProductIds": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 1
            }
          },
          "excludedProductIds": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 1
            }
          },
          "terms": {
            "type": "object",
            "properties": {
              "updatePolicy": {
                "type": "string",
                "enum": [
                  "existing_policy",
                  "current_major",
                  "all_versions"
                ],
                "description": "Older values are accepted but new saved terms normalize to all_versions. Product ownership is not a paid-major gate."
              },
              "offlinePolicy": {
                "type": "string",
                "enum": [
                  "existing_policy",
                  "permanent_device",
                  "grace",
                  "online_only"
                ]
              },
              "contentProtection": {
                "type": "string",
                "enum": [
                  "protected",
                  "download_only",
                  "none"
                ]
              },
              "trialScope": {
                "type": "string",
                "enum": [
                  "root_only",
                  "offer_contents"
                ]
              },
              "trialDays": {
                "type": "integer",
                "enum": [
                  0,
                  7,
                  14,
                  30
                ]
              },
              "failedPaymentGraceDays": {
                "type": "integer",
                "enum": [
                  0,
                  3,
                  7,
                  14
                ]
              },
              "cancellationBehavior": {
                "type": "string",
                "enum": [
                  "access_until_period_end",
                  "lock_immediately"
                ]
              }
            },
            "additionalProperties": true
          },
          "membershipPreview": {
            "type": "object",
            "properties": {},
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      }
    },
    "deals": {
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "offerId": {
                "type": "string",
                "format": "uuid"
              },
              "campaignId": {
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": 1
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "status": {
                "type": "string",
                "enum": [
                  "active",
                  "retired"
                ]
              },
              "title": {
                "type": "string",
                "maxLength": 200
              },
              "discountType": {
                "type": "string",
                "enum": [
                  "percent_bps",
                  "amount_minor"
                ]
              },
              "discountValue": {
                "type": "integer",
                "minimum": 1
              },
              "currency": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "duration": {
                "type": "string",
                "enum": [
                  "first_period",
                  "limited_periods",
                  "ongoing"
                ]
              },
              "durationPeriods": {
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1200
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "startsAt": {
                "type": "string",
                "format": "date-time"
              },
              "endsAt": {
                "anyOf": [
                  {
                    "type": "string",
                    "format": "date-time"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "couponCode": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "stackingPolicy": {
                "type": "string",
                "enum": [
                  "exclusive",
                  "with_sale"
                ]
              },
              "eligibility": {
                "type": "object",
                "properties": {
                  "newCustomersOnly": {
                    "type": "boolean"
                  },
                  "returningCustomersAllowed": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": true
              }
            },
            "additionalProperties": true
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "status": {
                "const": "retired"
              }
            },
            "additionalProperties": true,
            "required": [
              "id",
              "status"
            ]
          }
        ]
      }
    }
  },
  "additionalProperties": true
}

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

Operation errors: PURCHASE_OPTIONS_UNAVAILABLE, OFFER_CHANGED, OFFER_CHECKOUT_NOT_READY, PRODUCT_NOT_PUBLISHED, PROTECTED_RELEASE_REQUIRED, OWNERSHIP_SUBSCRIPTION_BUNDLE_REQUIRED, PURCHASE_OPTION_CONFLICT, PURCHASE_OFFER_CURRENCY_UNSUPPORTED.

DELETE /api/products/{id}/purchase-options/{offerId}

Retire an offer without deleting accepted customer terms

Auth
Account Bearer session token
Scope
products.publish; product ownership and assigned-product access in the effective workspace.
Returns
HTTP 200: id, status.
Notes
Configure one or two distinct kinds on one product. New prices and fixed-amount deals require USD; unsupported currencies return 400 PURCHASE_OFFER_CURRENCY_UNSUPPORTED with field:currency. Existing recorded currencies are not converted or relabeled. New immutable terms/price versions do not rewrite previously accepted customer snapshots. Supply expectedVersionId when editing to detect stale state. Published offers need a published product, price and ready checkout. Versioned subscription prices use day, week, month or year with intervalCount from 1 to 365, subject to provider limits. Dedicated legacy subscription bundles retain their own monthly/yearly contract. Published subscriptions use fourteen-day payment recovery and cancellation through the paid period. keep_products publication belongs to the existing ownership subscription-bundle workflow; this editor returns OWNERSHIP_SUBSCRIPTION_BUNDLE_REQUIRED. Future inclusion is limited to recurring linked_expansions/developer_catalog rules. Product ownership spans that product releases; technical content compatibility remains separate. Returns only id and status; GET the configuration to read the retained terms. Publish, unpublish or retire the permitted product/offer action; ordinary edit authority is insufficient.
Request, response and error reference

No request body fields are read by this operation.

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "const": "retired"
    }
  },
  "additionalProperties": true,
  "required": [
    "id",
    "status"
  ]
}

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

GET /api/products/{id}/purchase-options/{offerId}/deals

Read the selected offer deals including retired entries

Auth
Account Bearer session token
Scope
products.view; product ownership and assigned-product access in the effective workspace.
Returns
HTTP 200: deals.
Notes
Read the permitted product configuration.
Request, response and error reference

No request body fields are read by this operation.

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "deals": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "offerId": {
            "type": "string",
            "format": "uuid"
          },
          "campaignId": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 1
              },
              {
                "type": "null"
              }
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "retired"
            ]
          },
          "title": {
            "type": "string",
            "maxLength": 200
          },
          "discountType": {
            "type": "string",
            "enum": [
              "percent_bps",
              "amount_minor"
            ]
          },
          "discountValue": {
            "type": "integer",
            "minimum": 1
          },
          "currency": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "duration": {
            "type": "string",
            "enum": [
              "first_period",
              "limited_periods",
              "ongoing"
            ]
          },
          "durationPeriods": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 1,
                "maximum": 1200
              },
              {
                "type": "null"
              }
            ]
          },
          "startsAt": {
            "type": "string",
            "format": "date-time"
          },
          "endsAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          },
          "couponCode": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "stackingPolicy": {
            "type": "string",
            "enum": [
              "exclusive",
              "with_sale"
            ]
          },
          "eligibility": {
            "type": "object",
            "properties": {
              "newCustomersOnly": {
                "type": "boolean"
              },
              "returningCustomersAllowed": {
                "type": "boolean"
              }
            },
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      }
    }
  },
  "additionalProperties": true
}

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

POST /api/products/{id}/purchase-options/{offerId}/deals

Create a versioned deal for one purchase option

Auth
Account Bearer session token
Scope
products.publish; product ownership and assigned-product access in the effective workspace.
Request fields
  • id: string
  • offerId: string
  • campaignId: value
  • status: active | retired
  • title: string (required)
  • discountType: percent_bps | amount_minor (required)
  • discountValue: integer (required)
  • currency: value
  • duration: first_period | limited_periods | ongoing
  • durationPeriods: value
  • startsAt: string (required)
  • endsAt: value
  • couponCode: value
  • stackingPolicy: exclusive | with_sale
  • eligibility: object
  • replacesPromotionId: string
Returns
HTTP 200: id, offerId, campaignId, status, title, discountType, discountValue, currency, duration, durationPeriods, startsAt, endsAt, couponCode, stackingPolicy, eligibility.
Notes
Percent values are basis points, not whole percentages. A fixed discount uses integer minor units and matching currency. Starts and ends are timestamps; end must follow start. One-time deals cover one purchase. Recurring deals distinguish first_period, limited_periods and ongoing. Versioned automatic deals and subscription payments retain their own minimum checks; a one-time coupon reduction is checked against the final paid cart. replacesPromotionId identifies a saved deal replaced by this new immutable record. Publish, unpublish or retire the permitted product/offer action; ordinary edit authority is insufficient.
Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "offerId": {
      "type": "string",
      "format": "uuid"
    },
    "campaignId": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "retired"
      ]
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "pattern": "\\S"
    },
    "discountType": {
      "type": "string",
      "enum": [
        "percent_bps",
        "amount_minor"
      ]
    },
    "discountValue": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "currency": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^[uU][sS][dD]$",
          "description": "USD only. New price currency defaults to usd when omitted; no currency conversion is performed."
        },
        {
          "type": "null"
        }
      ]
    },
    "duration": {
      "type": "string",
      "enum": [
        "first_period",
        "limited_periods",
        "ongoing"
      ]
    },
    "durationPeriods": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 1,
          "maximum": 1200
        },
        {
          "type": "null"
        }
      ]
    },
    "startsAt": {
      "type": "string",
      "format": "date-time"
    },
    "endsAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    },
    "couponCode": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{0,64}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "stackingPolicy": {
      "type": "string",
      "enum": [
        "exclusive",
        "with_sale"
      ]
    },
    "eligibility": {
      "type": "object",
      "properties": {
        "newCustomersOnly": {
          "type": "boolean"
        },
        "returningCustomersAllowed": {
          "type": "boolean"
        }
      },
      "additionalProperties": false
    },
    "replacesPromotionId": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": true,
  "required": [
    "title",
    "discountType",
    "discountValue",
    "startsAt"
  ],
  "allOf": [
    {
      "if": {
        "properties": {
          "discountType": {
            "const": "amount_minor"
          }
        },
        "required": [
          "discountType"
        ]
      },
      "then": {
        "properties": {
          "currency": {
            "type": "string",
            "pattern": "^[uU][sS][dD]$",
            "description": "USD only. New price currency defaults to usd when omitted; no currency conversion is performed."
          }
        },
        "required": [
          "currency"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "discountType": {
            "const": "percent_bps"
          }
        },
        "required": [
          "discountType"
        ]
      },
      "then": {
        "properties": {
          "discountValue": {
            "maximum": 10000
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "duration": {
            "const": "limited_periods"
          }
        },
        "required": [
          "duration"
        ]
      },
      "then": {
        "properties": {
          "durationPeriods": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1200
          }
        },
        "required": [
          "durationPeriods"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "duration": {
            "const": "ongoing"
          }
        },
        "required": [
          "duration"
        ]
      },
      "then": {
        "properties": {
          "durationPeriods": {
            "type": "null"
          }
        }
      }
    },
    {
      "if": {
        "anyOf": [
          {
            "not": {
              "required": [
                "duration"
              ]
            }
          },
          {
            "properties": {
              "duration": {
                "const": "first_period"
              }
            },
            "required": [
              "duration"
            ]
          }
        ]
      },
      "then": {
        "properties": {
          "durationPeriods": {
            "anyOf": [
              {
                "const": 1
              },
              {
                "type": "null"
              }
            ]
          }
        }
      }
    }
  ]
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "offerId": {
      "type": "string",
      "format": "uuid"
    },
    "campaignId": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "retired"
      ]
    },
    "title": {
      "type": "string",
      "maxLength": 200
    },
    "discountType": {
      "type": "string",
      "enum": [
        "percent_bps",
        "amount_minor"
      ]
    },
    "discountValue": {
      "type": "integer",
      "minimum": 1
    },
    "currency": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "duration": {
      "type": "string",
      "enum": [
        "first_period",
        "limited_periods",
        "ongoing"
      ]
    },
    "durationPeriods": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 1,
          "maximum": 1200
        },
        {
          "type": "null"
        }
      ]
    },
    "startsAt": {
      "type": "string",
      "format": "date-time"
    },
    "endsAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    },
    "couponCode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "stackingPolicy": {
      "type": "string",
      "enum": [
        "exclusive",
        "with_sale"
      ]
    },
    "eligibility": {
      "type": "object",
      "properties": {
        "newCustomersOnly": {
          "type": "boolean"
        },
        "returningCustomersAllowed": {
          "type": "boolean"
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}

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

Operation errors: PURCHASE_OFFER_CURRENCY_UNSUPPORTED.

DELETE /api/products/{id}/purchase-options/{offerId}/deals/{promotionId}

Retire a deal without rewriting accepted subscription pricing

Auth
Account Bearer session token
Scope
products.publish; product ownership and assigned-product access in the effective workspace.
Returns
HTTP 200: id, status.
Notes
Returns only id and status, not a complete deal record. Read the selected offer deals separately for retained history. Publish, unpublish or retire the permitted product/offer action; ordinary edit authority is insufficient.
Request, response and error reference

No request body fields are read by this operation.

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "const": "retired"
    }
  },
  "additionalProperties": true,
  "required": [
    "id",
    "status"
  ]
}

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

SoundSync

Read the saved product choices

Read-only request with your permitted developer session
curl --fail-with-body -sS "$SOUNDSYNC_API_BASE/api/products/$PRODUCT_ID/purchase-options" \
  -H "Authorization: Bearer $SOUNDSYNC_ACCOUNT_TOKEN"

SoundSync

Illustrative unpublished offer body

PUT configuration changes a product; use a test product and review before publication
{
  "offers": [
    {
      "kind": "subscription",
      "status": "draft",
      "fulfillmentMode": "access",
      "inclusionScope": "root_only",
      "includeFuture": false,
      "terms": {
        "offlinePolicy": "grace",
        "trialDays": 14,
        "failedPaymentGraceDays": 14,
        "cancellationBehavior": "access_until_period_end"
      },
      "price": {
        "amountMinor": 1999,
        "currency": "usd",
        "billingInterval": "month",
        "intervalCount": 1,
        "renewalPolicy": "locked"
      }
    }
  ]
}

SoundSync

Save and checkout identifiers

FieldUse
expectedVersionIdSupply the saved offer version when editing; stale state returns OFFER_CHANGED.
offerId, offerVersionId, priceVersionIdUse current public-catalog values for the selected choice at checkout. A conflict requires review, not an automatic replacement.
amountMinor / percent_bpsInteger currency minor units for prices and fixed deals; basis points for percentage deals. These are not floating-dollar price fields.
offersSave one or two distinct kinds. Omitting an existing kind does not retire it. Draft choices can be incomplete; publication requires a saved price and the supported recurring terms.
dealsEach action names a kind included in this save and supplies promotion or retirePromotionId. Use one action per entry; if both fields are supplied, retirement takes precedence.
retireOfferIds / retirePromotionIdExplicitly retire the saved reference. Retirement does not delete accepted customer history.
refreshCurrentCollectionDeliberate refresh of a fixed current collection, not an implicit effect of changing the price.

SoundSync

Related contracts

Checkout API

Quotes, selected offer versions and managed payment.

Purchase-options guide

Publication, inclusions and customer experience.

SoundSync

Choose how the product is sold

One listing can expose buy-once and recurring choices. The captured editor uses example prices; accepted customer terms remain separate from your next draft.

Purchase options - Example data; no live transaction or account change.