{ "openapi": "3.0.0", "paths": { "/v1/products/search": { "get": { "operationId": "searchProducts", "x-speakeasy-pagination": { "type": "offsetLimit", "inputs": [ { "name": "page_number", "in": "parameters", "type": "page" }, { "name": "page_size", "in": "parameters", "type": "limit" } ], "outputs": { "numPages": "$.pagination.total_pages", "results": "$.items" } }, "x-speakeasy-name-override": "search", "summary": "List all products", "description": "Search and retrieve a paginated list of products. Filter by status, billing type, and other criteria.", "parameters": [ { "name": "page_number", "required": false, "in": "query", "description": "The page number for pagination.", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "page_size", "required": false, "in": "query", "description": "The number of items per page.", "schema": { "default": 10, "example": 10, "type": "number" } }, { "name": "status", "required": false, "in": "query", "description": "Lifecycle status of the product: `active` or `archived`.", "schema": { "$ref": "#/components/schemas/ProductStatus" } } ], "responses": { "200": { "description": "Successfully retrieved products", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductListEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Products" ], "security": [ { "ApiKey": [] } ] } }, "/v1/products": { "post": { "operationId": "createProduct", "x-speakeasy-name-override": "create", "summary": "Creates a new product.", "description": "Create a new product for one-time payments, including free products with a 0 price, or subscriptions. Configure pricing, billing cycles, and features.", "parameters": [ { "name": "Idempotency-Key", "required": false, "in": "header", "description": "Optional key that makes retries return the originally created product instead of creating a duplicate.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Product creation payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProductRequestEntity" } } } }, "responses": { "200": { "description": "Successfully created a product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Products" ], "security": [ { "ApiKey": [] } ] } }, "/v1/products/{id}": { "get": { "operationId": "getProduct", "x-speakeasy-name-override": "get", "summary": "Get a product by ID", "description": "Retrieve a single product by its unique identifier.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The product ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Products" ], "security": [ { "ApiKey": [] } ] }, "patch": { "operationId": "updateProduct", "x-speakeasy-name-override": "update", "summary": "Update a product", "description": "Update a product. Only supplied fields change; a price change mints a new default price.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The product ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Product update payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProductRequestEntity" } } } }, "responses": { "200": { "description": "Successfully updated the product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Products" ], "security": [ { "ApiKey": [] } ] }, "delete": { "operationId": "archiveProduct", "x-speakeasy-name-override": "archive", "summary": "Archive a product", "description": "Archive a product (soft-delete). The product is retained for historical orders and subscriptions but can no longer be purchased.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The product ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully archived the product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Products" ], "security": [ { "ApiKey": [] } ] } }, "/v1/customers/list": { "get": { "operationId": "listCustomers", "x-speakeasy-pagination": { "type": "offsetLimit", "inputs": [ { "name": "page_number", "in": "parameters", "type": "page" }, { "name": "page_size", "in": "parameters", "type": "limit" } ], "outputs": { "numPages": "$.pagination.total_pages", "results": "$.items" } }, "x-speakeasy-name-override": "list", "summary": "List all customers", "description": "Retrieve a paginated list of all customers. Filter and search through your customer base.", "parameters": [ { "name": "page_number", "required": false, "in": "query", "description": "The page number for pagination.", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "page_size", "required": false, "in": "query", "description": "The number of items per page.", "schema": { "default": 50, "example": 50, "type": "number" } } ], "responses": { "200": { "description": "Successfully retrieved customers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerListEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Customers" ], "security": [ { "ApiKey": [] } ] } }, "/v1/customers/{id}/orders": { "get": { "operationId": "listCustomerOrders", "x-speakeasy-name-override": "getOrders", "summary": "List customer orders", "description": "Retrieve a paginated list of orders for a specific customer.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The unique identifier of the customer", "schema": { "type": "string" } }, { "name": "page_number", "required": false, "in": "query", "description": "The page number for pagination.", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "page_size", "required": false, "in": "query", "description": "The number of items per page.", "schema": { "default": 10, "example": 10, "type": "number" } } ], "responses": { "200": { "description": "Successfully retrieved customer orders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderListEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Customers" ], "security": [ { "ApiKey": [] } ] } }, "/v1/customers/{id}/subscriptions": { "get": { "operationId": "listCustomerSubscriptions", "x-speakeasy-name-override": "listSubscriptions", "summary": "List customer subscriptions", "description": "Retrieve a paginated list of subscriptions for a specific customer.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The unique identifier of the customer", "schema": { "type": "string" } }, { "name": "page_number", "required": false, "in": "query", "description": "The page number for pagination.", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "page_size", "required": false, "in": "query", "description": "The number of items per page.", "schema": { "default": 10, "example": 10, "type": "number" } } ], "responses": { "200": { "description": "Successfully retrieved customer subscriptions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionListEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Customers" ], "security": [ { "ApiKey": [] } ] } }, "/v1/customers/{id}/licenses": { "get": { "operationId": "listCustomerLicenses", "x-speakeasy-name-override": "listLicenses", "summary": "List customer licenses", "description": "Retrieve a paginated list of license keys for a specific customer.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The unique identifier of the customer", "schema": { "type": "string" } }, { "name": "page_number", "required": false, "in": "query", "description": "The page number for pagination.", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "page_size", "required": false, "in": "query", "description": "The number of items per page.", "schema": { "default": 10, "example": 10, "type": "number" } } ], "responses": { "200": { "description": "Successfully retrieved customer licenses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseListEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Customers" ], "security": [ { "ApiKey": [] } ] } }, "/v1/customers": { "get": { "operationId": "retrieveCustomer", "x-speakeasy-name-override": "retrieve", "summary": "Retrieve a customer", "description": "Retrieve customer information by ID or email. View purchase history, subscriptions, and profile details.", "parameters": [ { "name": "customer_id", "required": false, "in": "query", "description": "The unique identifier of the customer.", "schema": { "example": "cust_1234567890", "type": "string" } }, { "name": "email", "required": false, "in": "query", "description": "The email address of the customer.", "schema": { "example": "customer@example.com", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Customers" ], "security": [ { "ApiKey": [] } ] }, "post": { "operationId": "createCustomer", "x-speakeasy-name-override": "create", "summary": "Create a customer", "description": "Create a new customer record for the authenticated store.", "parameters": [], "requestBody": { "required": true, "description": "Customer creation payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerRequestEntity" } } } }, "responses": { "200": { "description": "Successfully created the customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Customers" ], "security": [ { "ApiKey": [] } ] }, "patch": { "operationId": "updateCustomer", "x-speakeasy-name-override": "update", "summary": "Update a customer", "parameters": [], "requestBody": { "required": true, "description": "Customer update payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomerRequestEntity" } } } }, "responses": { "200": { "description": "Successfully updated the customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Customers" ], "security": [ { "ApiKey": [] } ] } }, "/v1/customers/billing": { "post": { "operationId": "generateCustomerLinks", "x-speakeasy-name-override": "generateBillingLinks", "summary": "Generate Customer Links", "description": "Generate a customer portal link for managing billing, subscriptions, and payment methods.", "parameters": [], "requestBody": { "required": true, "description": "Customer portal link generation request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerPortalLinkRequestEntity" } } } }, "responses": { "200": { "description": "Successfully generated customer links", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLinksEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Customers" ], "security": [ { "ApiKey": [] } ] } }, "/v1/subscriptions": { "get": { "operationId": "retrieveSubscription", "x-speakeasy-name-override": "get", "summary": "Retrieve a subscription", "description": "Retrieve subscription details by ID. View status, billing cycle, customer info, and payment history.", "parameters": [ { "name": "subscription_id", "required": true, "in": "query", "description": "The unique identifier of the subscription", "schema": { "example": "sub_1234567890", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Subscriptions" ], "security": [ { "ApiKey": [] } ] } }, "/v1/subscriptions/search": { "get": { "operationId": "searchSubscriptions", "x-speakeasy-pagination": { "type": "offsetLimit", "inputs": [ { "name": "page_number", "in": "parameters", "type": "page" }, { "name": "page_size", "in": "parameters", "type": "limit" } ], "outputs": { "numPages": "$.pagination.total_pages", "results": "$.items" } }, "x-speakeasy-name-override": "search", "summary": "List all subscriptions", "description": "Search and retrieve a paginated list of subscriptions. View status, billing cycle, and customer info.", "parameters": [ { "name": "page_number", "required": false, "in": "query", "description": "The page number for pagination.", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "page_size", "required": false, "in": "query", "description": "The number of items per page.", "schema": { "default": 10, "example": 10, "type": "number" } } ], "responses": { "200": { "description": "Successfully retrieved subscriptions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionListEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Subscriptions" ], "security": [ { "ApiKey": [] } ] } }, "/v1/subscriptions/{id}/cancel": { "post": { "operationId": "cancelSubscription", "x-speakeasy-name-override": "cancel", "summary": "Cancel a subscription.", "description": "Cancel an active subscription immediately or schedule cancellation at period end.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The unique identifier of the subscription", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Subscription cancellation options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelSubscriptionRequestEntity" } } } }, "responses": { "200": { "description": "Successfully canceled a subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Subscriptions" ], "security": [ { "ApiKey": [] } ] } }, "/v1/subscriptions/{id}": { "post": { "operationId": "updateSubscription", "x-speakeasy-name-override": "update", "summary": "Update a subscription.", "description": "Modify subscription details like units, seats, or add-ons. Support proration and immediate billing options.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The unique identifier of the subscription", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Subscription update payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionRequestEntity" } } } }, "responses": { "200": { "description": "Successfully updated a subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Subscriptions" ], "security": [ { "ApiKey": [] } ] } }, "/v1/subscriptions/{id}/upgrade": { "post": { "operationId": "upgradeSubscription", "x-speakeasy-name-override": "upgrade", "summary": "Upgrade a subscription to a different product", "description": "Upgrade a subscription to a different product or plan. Handle proration and plan changes seamlessly.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The unique identifier of the subscription", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Subscription upgrade payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpgradeSubscriptionRequestEntity" } } } }, "responses": { "200": { "description": "Successfully upgraded the subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Subscriptions" ], "security": [ { "ApiKey": [] } ] } }, "/v1/subscriptions/{id}/pause": { "post": { "operationId": "pauseSubscription", "x-speakeasy-name-override": "pause", "summary": "Pause a subscription.", "description": "Temporarily pause a subscription. Stop billing while retaining the subscription for later resumption.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The unique identifier of the subscription", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully paused a subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Subscriptions" ], "security": [ { "ApiKey": [] } ] } }, "/v1/subscriptions/{id}/resume": { "post": { "operationId": "resumeSubscription", "x-speakeasy-name-override": "resume", "summary": "Resume a subscription.", "description": "Resume a subscription. Subscription must be in paused or scheduled_cancel status.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The unique identifier of the subscription", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully resumed a subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Subscriptions" ], "security": [ { "ApiKey": [] } ] } }, "/v1/checkouts": { "get": { "operationId": "retrieveCheckout", "x-speakeasy-name-override": "retrieve", "summary": "Retrieve a checkout session.", "description": "Retrieve details of a checkout session by ID. View status, customer info, and payment details.", "parameters": [ { "name": "checkout_id", "required": true, "in": "query", "description": "The ID of the checkout session to retrieve.", "schema": { "example": "chk_1234567890", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the checkout session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Checkouts" ], "security": [ { "ApiKey": [] } ] }, "post": { "operationId": "createCheckout", "x-speakeasy-name-override": "create", "summary": "Creates a new checkout session.", "description": "Create a new checkout session to accept one-time payments or start subscriptions. Returns a checkout URL to redirect customers.", "parameters": [], "requestBody": { "required": true, "description": "Create checkout request payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutRequest" } } } }, "responses": { "200": { "description": "Successfully created a checkout session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Checkouts" ], "security": [ { "ApiKey": [] } ] } }, "/v1/licenses/activate": { "post": { "operationId": "activateLicense", "x-speakeasy-name-override": "activate", "summary": "Activates a license key.", "description": "Activate a license key for a specific device or instance. Register new activations and track usage limits.", "parameters": [], "requestBody": { "required": true, "description": "License activation request payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateLicenseRequestEntity" } } } }, "responses": { "200": { "description": "Successfully activated a license key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Licenses" ], "security": [ { "ApiKey": [] } ] } }, "/v1/licenses/deactivate": { "post": { "operationId": "deactivateLicense", "x-speakeasy-name-override": "deactivate", "summary": "Deactivate a license key instance.", "description": "Remove a device activation from a license key. Free up activation slots for new devices.", "parameters": [], "requestBody": { "required": true, "description": "License deactivation request payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeactivateLicenseRequestEntity" } } } }, "responses": { "200": { "description": "Successfully deactivated a license key instance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Licenses" ], "security": [ { "ApiKey": [] } ] } }, "/v1/licenses/validate": { "post": { "operationId": "validateLicense", "x-speakeasy-name-override": "validate", "summary": "Validates a license key or instance.", "description": "Verify if a license key is valid and active for a specific instance. Check activation status and expiration.", "parameters": [], "requestBody": { "required": true, "description": "License validation request payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateLicenseRequestEntity" } } } }, "responses": { "200": { "description": "Successfully validated a license key instance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Licenses" ], "security": [ { "ApiKey": [] } ] } }, "/v1/licenses/{id}/instances": { "get": { "operationId": "listLicenseInstances", "x-speakeasy-pagination": { "type": "offsetLimit", "inputs": [ { "name": "page_number", "in": "parameters", "type": "page" }, { "name": "page_size", "in": "parameters", "type": "limit" } ], "outputs": { "numPages": "$.pagination.total_pages", "results": "$.items" } }, "x-speakeasy-name-override": "listInstances", "summary": "List license instances.", "description": "Retrieve a paginated list of instances (activations) for a license key. Use an instance id from this list to deactivate it via the deactivate endpoint.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The unique identifier of the license key", "schema": { "type": "string" } }, { "name": "page_number", "required": false, "in": "query", "description": "The page number for pagination.", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "page_size", "required": false, "in": "query", "description": "The number of items per page.", "schema": { "default": 10, "example": 10, "type": "number" } } ], "responses": { "200": { "description": "Successfully retrieved license instances", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseInstanceListEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Licenses" ], "security": [ { "ApiKey": [] } ] } }, "/v1/discounts/search": { "get": { "operationId": "searchDiscounts", "x-speakeasy-pagination": { "type": "offsetLimit", "inputs": [ { "name": "page_number", "in": "parameters", "type": "page" }, { "name": "page_size", "in": "parameters", "type": "limit" } ], "outputs": { "numPages": "$.pagination.total_pages", "results": "$.items" } }, "x-speakeasy-name-override": "search", "summary": "Search discounts", "description": "Search and list discount codes for a store with filters and pagination.", "parameters": [ { "name": "page_number", "required": false, "in": "query", "description": "The page number for pagination.", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "page_size", "required": false, "in": "query", "description": "The number of items per page.", "schema": { "default": 10, "example": 10, "type": "number" } }, { "name": "product_id", "required": false, "in": "query", "description": "Filter discounts that apply to a specific product.", "schema": { "example": "prod_1234567890", "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Filter by discount status.", "schema": { "enum": [ "active", "deleted" ], "type": "string" } }, { "name": "type", "required": false, "in": "query", "description": "Filter by discount type.", "schema": { "enum": [ "percentage", "fixed" ], "type": "string" } }, { "name": "created_after", "required": false, "in": "query", "description": "Filter discounts created after this date.", "schema": { "example": "2024-01-01T00:00:00Z", "type": "string" } }, { "name": "created_before", "required": false, "in": "query", "description": "Filter discounts created before this date.", "schema": { "example": "2024-12-31T23:59:59Z", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of discounts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscountListEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Discounts" ], "security": [ { "ApiKey": [] } ] } }, "/v1/discounts": { "get": { "operationId": "retrieveDiscount", "x-speakeasy-name-override": "get", "summary": "Retrieve discount", "description": "Retrieve discount code details by ID or code. Check usage limits, expiration, and discount amount.", "parameters": [ { "name": "discount_id", "required": false, "in": "query", "description": "The unique identifier of the discount (provide either discount_id OR discount_code).", "schema": { "example": "disc_1234567890", "type": "string" } }, { "name": "discount_code", "required": false, "in": "query", "description": "The unique discount code (provide either discount_id OR discount_code).", "schema": { "example": "SAVE20", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the discount", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscountEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Discounts" ], "security": [ { "ApiKey": [] } ] }, "post": { "operationId": "createDiscount", "x-speakeasy-name-override": "create", "summary": "Create a discount.", "description": "Create promotional discount codes for products. Set percentage or fixed amount discounts with expiration dates.", "parameters": [], "requestBody": { "required": true, "description": "Discount creation payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDiscountRequestEntity" } } } }, "responses": { "200": { "description": "Successfully created a discount", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscountEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Discounts" ], "security": [ { "ApiKey": [] } ] } }, "/v1/discounts/{id}/delete": { "delete": { "operationId": "deleteDiscount", "x-speakeasy-name-override": "delete", "summary": "Delete a discount.", "description": "Permanently delete a discount code. Prevent further usage of the discount.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The unique identifier of the discount to delete", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully deleted a discount", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscountEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Discounts" ], "security": [ { "ApiKey": [] } ] } }, "/v1/transactions": { "get": { "operationId": "getTransactionById", "x-speakeasy-name-override": "getById", "summary": "Get a transaction by ID", "description": "Retrieve a single transaction by ID. View payment details, status, and associated order information.", "parameters": [ { "name": "transaction_id", "required": true, "in": "query", "description": "The unique identifier of the transaction.", "schema": { "example": "txn_1234567890", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Transactions" ], "security": [ { "ApiKey": [] } ] } }, "/v1/transactions/search": { "get": { "operationId": "searchTransactions", "x-speakeasy-pagination": { "type": "offsetLimit", "inputs": [ { "name": "page_number", "in": "parameters", "type": "page" }, { "name": "page_size", "in": "parameters", "type": "limit" } ], "outputs": { "numPages": "$.pagination.total_pages", "results": "$.items" } }, "x-speakeasy-name-override": "search", "summary": "List all transactions", "description": "Search and retrieve payment transactions. Filter by customer, product, date range, and status.", "parameters": [ { "name": "customer_id", "required": false, "in": "query", "description": "Filter transactions by customer ID.", "schema": { "example": "cust_1234567890", "type": "string" } }, { "name": "order_id", "required": false, "in": "query", "description": "Filter transactions by order ID.", "schema": { "example": "ord_1234567890", "type": "string" } }, { "name": "product_id", "required": false, "in": "query", "description": "Filter transactions by product ID.", "schema": { "example": "prod_1234567890", "type": "string" } }, { "name": "page_number", "required": false, "in": "query", "description": "The page number for pagination.", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "page_size", "required": false, "in": "query", "description": "The number of items per page.", "schema": { "default": 10, "example": 10, "type": "number" } } ], "responses": { "200": { "description": "Successfully retrieved transactions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionListEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Transactions" ], "security": [ { "ApiKey": [] } ] } }, "/v1/stats/summary": { "get": { "operationId": "getMetricsSummary", "x-speakeasy-name-override": "getSummary", "summary": "Get store metrics summary", "description": "Retrieve aggregated store metrics including counts, revenue, and MRR. When startDate and endDate are provided, totals are filtered to that date range. When interval is also provided, the response includes a periods array with time-series data points grouped by that interval. The periods array starts from the store's first transaction or startDate, whichever is later, to avoid empty leading buckets. All monetary amounts are in cents (integer, no decimals).", "parameters": [ { "name": "startDate", "required": false, "in": "query", "description": "Start of the date range as a Unix timestamp in milliseconds (e.g. 1740614400000). When provided with endDate, filters totals to this range. Required when interval is specified.", "schema": { "type": "number" } }, { "name": "endDate", "required": false, "in": "query", "description": "End of the date range as a Unix timestamp in milliseconds (e.g. 1772150400000). When provided with startDate, filters totals to this range. Required when interval is specified.", "schema": { "type": "number" } }, { "name": "interval", "required": false, "in": "query", "description": "Groups time-series data into buckets of this size. Requires startDate and endDate. Returns a periods array with one entry per bucket containing grossRevenue and netRevenue.", "schema": { "enum": [ "day", "week", "month" ], "type": "string" } }, { "name": "currency", "required": true, "in": "query", "schema": { "enum": [ "EUR", "USD" ], "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved store metrics summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatsSummaryEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Stats" ], "security": [ { "ApiKey": [] } ] } }, "/v1/moderation/prompt": { "post": { "operationId": "screenPrompt", "x-speakeasy-name-override": "screenPrompt", "summary": "Screen a prompt", "description": "Evaluate a text prompt against content policies before generation. This endpoint is experimental and may change.", "parameters": [], "requestBody": { "required": true, "description": "Prompt screening request payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScreenPromptRequest" } } } }, "responses": { "200": { "description": "Prompt screening result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScreenPromptResponse" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Moderation" ], "security": [ { "ApiKey": [] } ] } }, "/v1/refunds": { "post": { "operationId": "refundPayment", "x-speakeasy-name-override": "refund", "x-speakeasy-group": "transactions", "summary": "Refund a payment", "description": "Issue a full refund for a payment, identified by its transaction ID. The full remaining refundable amount is resolved automatically. Returns `pending` when the payment provider confirms the refund asynchronously.", "parameters": [], "requestBody": { "required": true, "description": "The transaction to refund in full.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRefundRequestEntity" } } } }, "responses": { "200": { "description": "Successfully created the refund", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundResponseEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Refunds" ], "security": [ { "ApiKey": [] } ] } }, "/v1/customer-credits/accounts": { "post": { "operationId": "createCustomerCreditsAccount", "x-speakeasy-name-override": "createAccount", "x-speakeasy-group": "customerCredits", "summary": "Create a customer credits account", "description": "Create a new credits account for a customer. Optionally seed it with an initial balance.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountDto" } } } }, "responses": { "201": { "description": "Account created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Customer Credits - Accounts (Experimental)" ], "security": [ { "ApiKey": [] } ] }, "get": { "operationId": "listCustomerCreditsAccounts", "x-speakeasy-pagination": { "type": "cursor", "inputs": [ { "name": "starting_after", "in": "parameters", "type": "cursor" }, { "name": "limit", "in": "parameters", "type": "limit" } ], "outputs": { "nextCursor": "$.data[-1].id", "results": "$.data" } }, "x-speakeasy-name-override": "listAccounts", "x-speakeasy-group": "customerCredits", "summary": "List customer credits accounts", "description": "List accounts for the authenticated store with cursor pagination. System accounts are excluded.", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Maximum number of accounts to return", "schema": { "minimum": 1, "maximum": 100, "default": 10, "type": "number" } }, { "name": "customer_id", "required": false, "in": "query", "description": "Filter by owner ID (e.g. customer ID)", "schema": { "example": "cust_abc123", "type": "string" } }, { "name": "starting_after", "required": false, "in": "query", "description": "Cursor for forward pagination — account ID to start after", "schema": { "type": "string" } }, { "name": "ending_before", "required": false, "in": "query", "description": "Cursor for backward pagination — account ID to end before", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of accounts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountListResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Customer Credits - Accounts (Experimental)" ], "security": [ { "ApiKey": [] } ] } }, "/v1/customer-credits/accounts/{id}": { "get": { "operationId": "getCustomerCreditsAccount", "x-speakeasy-name-override": "getAccount", "x-speakeasy-group": "customerCredits", "summary": "Retrieve a customer credits account", "description": "Get details of a customer credits account by ID.", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Customer Credits - Accounts (Experimental)" ], "security": [ { "ApiKey": [] } ] } }, "/v1/customer-credits/accounts/{id}/balance": { "get": { "operationId": "getCustomerCreditsAccountBalance", "x-speakeasy-name-override": "getAccountBalance", "x-speakeasy-group": "customerCredits", "summary": "Get account balance", "description": "Get the current balance of an account. Optionally pass ?at= for historical balance.", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "at", "required": false, "in": "query", "description": "ISO 8601 date. If present, computes balance at that point in time. If absent, returns O(1) projected balance.", "schema": { "example": "2024-01-15T00:00:00.000Z", "type": "string" } } ], "responses": { "200": { "description": "Account balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Customer Credits - Accounts (Experimental)" ], "security": [ { "ApiKey": [] } ] } }, "/v1/customer-credits/accounts/{id}/entries": { "get": { "operationId": "listCustomerCreditsAccountEntries", "x-speakeasy-pagination": { "type": "cursor", "inputs": [ { "name": "starting_after", "in": "parameters", "type": "cursor" }, { "name": "limit", "in": "parameters", "type": "limit" } ], "outputs": { "nextCursor": "$.data[-1].id", "results": "$.data" } }, "x-speakeasy-name-override": "listEntries", "x-speakeasy-group": "customerCredits", "summary": "List account entries", "description": "List the credit and debit history for an account with cursor pagination.", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of entries to return", "schema": { "minimum": 1, "maximum": 100, "default": 10, "type": "number" } }, { "name": "starting_after", "required": false, "in": "query", "description": "Cursor for forward pagination — entry ID to start after", "schema": { "type": "string" } }, { "name": "ending_before", "required": false, "in": "query", "description": "Cursor for backward pagination — entry ID to end before", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntryListResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Customer Credits - Accounts (Experimental)" ], "security": [ { "ApiKey": [] } ] } }, "/v1/customer-credits/accounts/{id}/freeze": { "post": { "operationId": "freezeCustomerCreditsAccount", "x-speakeasy-name-override": "freezeAccount", "x-speakeasy-group": "customerCredits", "summary": "Freeze an account", "description": "Freeze an account to prevent new transactions.", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account frozen", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" }, "409": { "description": "Account already frozen or closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreditsErrorResponseDto" } } } } }, "tags": [ "Customer Credits - Accounts (Experimental)" ], "security": [ { "ApiKey": [] } ] } }, "/v1/customer-credits/accounts/{id}/unfreeze": { "post": { "operationId": "unfreezeCustomerCreditsAccount", "x-speakeasy-name-override": "unfreezeAccount", "x-speakeasy-group": "customerCredits", "summary": "Unfreeze an account", "description": "Unfreeze a frozen account to allow transactions again.", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account unfrozen", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" }, "409": { "description": "Account is not frozen or is closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreditsErrorResponseDto" } } } } }, "tags": [ "Customer Credits - Accounts (Experimental)" ], "security": [ { "ApiKey": [] } ] } }, "/v1/customer-credits/accounts/{id}/credit": { "post": { "operationId": "creditCustomerCreditsAccount", "x-speakeasy-name-override": "creditAccount", "x-speakeasy-group": "customerCredits", "summary": "Credit an account", "description": "Add credits to a customer account. Returns the resulting transaction record.", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditDebitRequestDto" } } } }, "responses": { "201": { "description": "Credit transaction created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" }, "409": { "description": "Account frozen or closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreditsErrorResponseDto" } } } } }, "tags": [ "Customer Credits - Accounts (Experimental)" ], "security": [ { "ApiKey": [] } ] } }, "/v1/customer-credits/accounts/{id}/debit": { "post": { "operationId": "debitCustomerCreditsAccount", "x-speakeasy-name-override": "debitAccount", "x-speakeasy-group": "customerCredits", "summary": "Debit an account", "description": "Deduct credits from a customer account. Returns the resulting transaction record.", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditDebitRequestDto" } } } }, "responses": { "201": { "description": "Debit transaction created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" }, "409": { "description": "Account frozen or closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreditsErrorResponseDto" } } } } }, "tags": [ "Customer Credits - Accounts (Experimental)" ], "security": [ { "ApiKey": [] } ] } }, "/v1/customer-credits/accounts/{id}/reverse": { "post": { "operationId": "reverseCustomerCreditsAccountTransaction", "x-speakeasy-name-override": "reverseTransaction", "x-speakeasy-group": "customerCredits", "summary": "Reverse a transaction", "description": "Reverse a previous credit or debit on this account. Creates a new transaction that undoes the original, preserving the full history.", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReverseTransactionRequestDto" } } } }, "responses": { "201": { "description": "Reversal transaction created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Customer Credits - Accounts (Experimental)" ], "security": [ { "ApiKey": [] } ] } }, "/v1/customer-credits/accounts/{id}/close": { "post": { "operationId": "closeCustomerCreditsAccount", "x-speakeasy-name-override": "closeAccount", "x-speakeasy-group": "customerCredits", "summary": "Close an account", "description": "Permanently close an account. This action cannot be undone.", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" }, "409": { "description": "Account already closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreditsErrorResponseDto" } } } } }, "tags": [ "Customer Credits - Accounts (Experimental)" ], "security": [ { "ApiKey": [] } ] } }, "/v1/affiliates/invites": { "post": { "operationId": "createAffiliateInvite", "x-speakeasy-name-override": "createInvite", "summary": "Create an affiliate invitation", "description": "Invite someone to your affiliate program by email. They receive an invitation email and become an active affiliate once they accept. If `program_id` is omitted, the invitation is created for your store's affiliate program.", "parameters": [], "requestBody": { "required": true, "description": "Affiliate invitation payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAffiliateInviteRequestEntity" } } } }, "responses": { "200": { "description": "Successfully created the affiliate invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AffiliateInviteEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" }, "409": { "description": "Conflict - an invitation has already been sent to this email address" } }, "tags": [ "Affiliates" ], "security": [ { "ApiKey": [] } ] }, "get": { "operationId": "listAffiliateInvites", "x-speakeasy-pagination": { "type": "offsetLimit", "inputs": [ { "name": "page_number", "in": "parameters", "type": "page" }, { "name": "page_size", "in": "parameters", "type": "limit" } ], "outputs": { "numPages": "$.pagination.total_pages", "results": "$.items" } }, "x-speakeasy-name-override": "listInvites", "summary": "List affiliate invitations", "description": "Retrieve a paginated list of the invitations you have sent, with their status (`pending` until accepted, `accepted` once the affiliate has joined).", "parameters": [ { "name": "page_number", "required": false, "in": "query", "description": "The page number for pagination.", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "page_size", "required": false, "in": "query", "description": "The number of items per page.", "schema": { "default": 50, "example": 50, "type": "number" } } ], "responses": { "200": { "description": "Successfully retrieved affiliate invitations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AffiliateInviteListEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Affiliates" ], "security": [ { "ApiKey": [] } ] } }, "/v1/affiliates": { "get": { "operationId": "listAffiliates", "x-speakeasy-pagination": { "type": "offsetLimit", "inputs": [ { "name": "page_number", "in": "parameters", "type": "page" }, { "name": "page_size", "in": "parameters", "type": "limit" } ], "outputs": { "numPages": "$.pagination.total_pages", "results": "$.items" } }, "x-speakeasy-name-override": "list", "summary": "List all affiliates", "description": "Retrieve a paginated list of your affiliates with their referral link, click and conversion counts, and lifetime commission. Affiliates who were invited but have not yet joined a program are not included.", "parameters": [ { "name": "page_number", "required": false, "in": "query", "description": "The page number for pagination.", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "page_size", "required": false, "in": "query", "description": "The number of items per page.", "schema": { "default": 50, "example": 50, "type": "number" } } ], "responses": { "200": { "description": "Successfully retrieved affiliates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AffiliateListEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Affiliates" ], "security": [ { "ApiKey": [] } ] } }, "/v1/affiliates/{id}": { "get": { "operationId": "retrieveAffiliate", "x-speakeasy-name-override": "retrieve", "summary": "Retrieve an affiliate", "description": "Retrieve a single affiliate by ID, including referral link, click and conversion counts, and lifetime commission.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The unique identifier of the affiliate", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the affiliate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AffiliateEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Affiliates" ], "security": [ { "ApiKey": [] } ] } }, "/v1/affiliates/{id}/commissions": { "get": { "operationId": "listAffiliateCommissions", "x-speakeasy-pagination": { "type": "offsetLimit", "inputs": [ { "name": "page_number", "in": "parameters", "type": "page" }, { "name": "page_size", "in": "parameters", "type": "limit" } ], "outputs": { "numPages": "$.pagination.total_pages", "results": "$.items" } }, "x-speakeasy-name-override": "listCommissions", "summary": "List affiliate commissions", "description": "Retrieve a paginated list of an affiliate’s commissions. Filter by settlement status (pending, approved, paid).", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The unique identifier of the affiliate", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "The settlement status of the commission. `pending` while on hold, `approved` once cleared and available, `paid` once settled by a payout.", "schema": { "$ref": "#/components/schemas/CommissionStatus" } }, { "name": "page_number", "required": false, "in": "query", "description": "The page number for pagination.", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "page_size", "required": false, "in": "query", "description": "The number of items per page.", "schema": { "default": 10, "example": 10, "type": "number" } } ], "responses": { "200": { "description": "Successfully retrieved affiliate commissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommissionListEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Affiliates" ], "security": [ { "ApiKey": [] } ] } }, "/v1/splits": { "post": { "operationId": "createSplit", "x-speakeasy-name-override": "create", "summary": "Create a split", "description": "Create a revenue split for your store. The split applies either to your whole store (`type: store`) or to a single product (`type: product`). Recipients are existing stores (added directly) or email invitees; a split created with any email invitee starts disabled and activates once the first invitee accepts. The split is always created for the store the API key belongs to.", "parameters": [], "requestBody": { "required": true, "description": "Split creation payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSplitRequestEntity" } } } }, "responses": { "200": { "description": "Successfully created the split", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SplitEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Splits" ], "security": [ { "ApiKey": [] } ] }, "get": { "operationId": "listSplits", "x-speakeasy-pagination": { "type": "offsetLimit", "inputs": [ { "name": "page_number", "in": "parameters", "type": "page" }, { "name": "page_size", "in": "parameters", "type": "limit" } ], "outputs": { "numPages": "$.pagination.total_pages", "results": "$.items" } }, "x-speakeasy-name-override": "list", "summary": "List all splits", "description": "Retrieve a paginated list of the active splits configured for your store, each with its recipients and their shares. Email invitees who have not yet accepted are shown with a masked email address.", "parameters": [ { "name": "page_number", "required": false, "in": "query", "description": "The page number for pagination.", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "page_size", "required": false, "in": "query", "description": "The number of items per page.", "schema": { "default": 50, "example": 50, "type": "number" } } ], "responses": { "200": { "description": "Successfully retrieved splits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SplitListEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Splits" ], "security": [ { "ApiKey": [] } ] } }, "/v1/splits/{id}": { "get": { "operationId": "retrieveSplit", "x-speakeasy-name-override": "retrieve", "summary": "Retrieve a split", "description": "Retrieve a single split by ID, including its recipients and their shares. Email invitees who have not yet accepted are shown with a masked email address and their invite status. Splits belonging to another store are not visible.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The unique identifier of the split", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the split", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SplitEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Splits" ], "security": [ { "ApiKey": [] } ] }, "delete": { "operationId": "deleteSplit", "x-speakeasy-name-override": "delete", "summary": "Delete a split", "description": "Delete a split by ID. The split stops applying to future payments immediately. Splits belonging to another store cannot be deleted.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The unique identifier of the split", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully deleted the split", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SplitEntity" } } } }, "400": { "description": "Bad Request - Invalid input parameters" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Not Found - Resource does not exist" } }, "tags": [ "Splits" ], "security": [ { "ApiKey": [] } ] } } }, "info": { "title": "Creem API", "description": "Creem is an all-in-one platform for managing subscriptions and recurring revenue, tailored specifically for today's SaaS companies. It enables you to boost revenue, enhance customer retention, and scale your operations seamlessly.", "version": "v1", "contact": { "name": "Creem Support", "url": "https://creem.io", "email": "support@creem.io" }, "license": { "name": "Commercial", "url": "https://creem.io/terms" }, "termsOfService": "https://creem.io/terms" }, "tags": [], "servers": [ { "url": "https://api.creem.io", "description": "Production — live API for processing real transactions and data.", "x-speakeasy-server-id": "prod" }, { "url": "https://test-api.creem.io", "description": "Test — sandbox API for development and testing with no real charges.", "x-speakeasy-server-id": "test" } ], "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key for authentication. You can find your API key in the Creem dashboard under Settings > API Keys." } }, "schemas": { "ProductStatus": { "type": "string", "description": "Lifecycle status of the product: `active` or `archived`.", "enum": [ "active", "archived" ] }, "EnvironmentMode": { "type": "string", "description": "String representing the environment.", "enum": [ "test", "prod", "sandbox" ] }, "ProductFeatureType": { "type": "string", "description": "The type of the feature: `custom` (private note), `file` (downloadable files), `licenseKey` (license key), or `customerCredits` (customer credit grant).", "enum": [ "custom", "file", "licenseKey", "customerCredits" ] }, "FeatureEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the feature.", "example": "feat_abc123" }, "type": { "example": "licenseKey", "$ref": "#/components/schemas/ProductFeatureType" }, "description": { "type": "string", "description": "A brief description of the feature.", "example": "Access to premium course materials." } }, "required": [ "id", "type", "description" ] }, "ProductBillingType": { "type": "string", "description": "Indicates the billing method for the customer. It can either be a `recurring` billing cycle or a `onetime` payment.", "enum": [ "recurring", "onetime" ] }, "ProductBillingPeriod": { "type": "string", "description": "Billing period", "enum": [ "every-month", "every-three-months", "every-six-months", "every-year", "every-day", "once", "custom" ] }, "TaxMode": { "type": "string", "description": "Specifies the tax calculation mode for the transaction. If set to \"inclusive,\" the tax is included in the price. If set to \"exclusive,\" the tax is added on top of the price.", "enum": [ "inclusive", "exclusive" ] }, "TaxCategory": { "type": "string", "description": "Categorizes the type of product or service for tax purposes. This helps determine the applicable tax rules based on the nature of the item or service.", "enum": [ "saas", "digital-goods-service", "ebooks" ] }, "CustomFieldType": { "type": "string", "description": "The type of the field.", "enum": [ "text", "checkbox" ] }, "Text": { "type": "object", "properties": { "max_length": { "type": "number", "description": "Maximum character length constraint for the input.", "nullable": true }, "minimum_length": { "type": "number", "description": "Minimum character length requirement for the input.", "nullable": true }, "value": { "type": "string", "description": "The value of the input.", "nullable": true } } }, "Checkbox": { "type": "object", "properties": { "label": { "type": "string", "description": "The markdown text to display for the checkbox.", "nullable": true }, "value": { "type": "boolean", "description": "The value of the checkbox (checked or not).", "nullable": true } } }, "CustomField": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/CustomFieldType" }, "key": { "type": "string", "description": "Unique key for custom field. Must be unique to this field, alphanumeric, and up to 200 characters.", "maxLength": 200 }, "label": { "type": "string", "description": "The label for the field, displayed to the customer, up to 50 characters", "maxLength": 200 }, "optional": { "type": "boolean", "description": "Whether the customer is required to complete the field. Defaults to `false`.", "nullable": true }, "text": { "description": "Configuration for text field type.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Text" } ] }, "checkbox": { "description": "Configuration for checkbox field type.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Checkbox" } ] } }, "required": [ "type", "key", "label" ] }, "ProductEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object." }, "mode": { "$ref": "#/components/schemas/EnvironmentMode" }, "object": { "type": "string", "description": "String representing the object's type. Objects of the same type share the same value." }, "name": { "type": "string", "description": "The name of the product" }, "description": { "type": "string", "description": "A brief description of the product", "example": "This is a sample product description." }, "image_url": { "type": "string", "description": "URL of the product image. Only png as jpg are supported", "example": "https://example.com/image.jpg" }, "image_urls": { "description": "Ordered list of product image URLs. The first entry is the cover image (mirrored in image_url).", "example": [ "https://example.com/image.jpg" ], "type": "array", "items": { "type": "string" } }, "features": { "description": "Features of the product.", "type": "array", "items": { "$ref": "#/components/schemas/FeatureEntity" } }, "price": { "type": "number", "description": "The price of the product in cents. 1000 = $10.00", "example": 400 }, "currency": { "type": "string", "description": "Three-letter ISO currency code, in uppercase. Must be a supported currency.", "example": "USD" }, "billing_type": { "example": "recurring", "$ref": "#/components/schemas/ProductBillingType" }, "billing_period": { "example": "every-month", "$ref": "#/components/schemas/ProductBillingPeriod" }, "recurring_interval": { "type": "object", "description": "The unit of the recurring billing interval (`day`, `week`, `month`, or `year`). Together with `recurring_interval_count` this is authoritative for renewal timing — a `billing_period` of `custom` cannot be interpreted without it. For presets it is derived from the cadence (e.g. `every-three-months` → `month`). `null` for one-time products.", "example": "month", "nullable": true }, "recurring_interval_count": { "type": "object", "description": "The number of `recurring_interval` units per billing cycle (e.g. `3` with a `month` interval bills every three months). Together with `recurring_interval` this is authoritative for renewal timing. For presets it is derived from the cadence. `null` for one-time products.", "example": 3, "nullable": true }, "status": { "example": "active", "$ref": "#/components/schemas/ProductStatus" }, "tax_mode": { "example": "inclusive", "$ref": "#/components/schemas/TaxMode" }, "tax_category": { "example": "saas", "$ref": "#/components/schemas/TaxCategory" }, "product_url": { "type": "string", "description": "The product page you can redirect your customers to for express checkout.", "example": "https://creem.io/product/prod_123123123123" }, "default_success_url": { "type": "string", "description": "The URL to which the user will be redirected after successfull payment.", "example": "https://example.com/?status=successful", "nullable": true }, "custom_fields": { "description": "Custom fields configured for the product. Collect additional information from your customer during checkout.", "nullable": true, "type": "array", "items": { "$ref": "#/components/schemas/CustomField" } }, "created_at": { "format": "date-time", "type": "string", "description": "Creation date of the product", "example": "2023-01-01T00:00:00Z" }, "updated_at": { "format": "date-time", "type": "string", "description": "Last updated date of the product", "example": "2023-01-01T00:00:00Z" } }, "required": [ "id", "mode", "object", "name", "description", "price", "currency", "billing_type", "billing_period", "status", "tax_mode", "tax_category", "created_at", "updated_at" ] }, "PaginationEntity": { "type": "object", "properties": { "total_records": { "type": "number", "description": "Total number of records in the list", "example": 0 }, "total_pages": { "type": "number", "description": "Total number of pages available", "example": 0 }, "current_page": { "type": "number", "description": "The current page number", "example": 1 }, "next_page": { "type": "number", "description": "The next page number, or null if there is no next page", "example": 2, "nullable": true }, "prev_page": { "type": "number", "description": "The previous page number, or null if there is no previous page", "example": null, "nullable": true } }, "required": [ "total_records", "total_pages", "current_page", "next_page", "prev_page" ] }, "ProductListEntity": { "type": "object", "properties": { "items": { "description": "List of product items", "items": { "$ref": "#/components/schemas/ProductEntity" }, "type": "array" }, "pagination": { "description": "Pagination details for the list", "allOf": [ { "$ref": "#/components/schemas/PaginationEntity" } ] } }, "required": [ "items", "pagination" ] }, "ProductCurrency": { "type": "string", "description": "Three-letter uppercase ISO 4217 currency code. Must be one of Creem's supported currencies.", "enum": [ "EUR", "USD" ] }, "ProductRequestBillingType": { "type": "string", "description": "Billing method for the product: `recurring` subscription or `onetime` payment.", "enum": [ "recurring", "onetime" ] }, "ProductRequestBillingPeriod": { "type": "string", "description": "Billing interval. Required when `billing_type` is `recurring`. Use a preset for the common cadences, or `custom` together with `recurring_interval` + `recurring_interval_count` for anything else (e.g. weekly).", "enum": [ "once", "every-day", "every-month", "every-three-months", "every-six-months", "every-year", "custom" ] }, "ProductRequestRecurringInterval": { "type": "string", "description": "Unit of a custom billing period. Required when `billing_period` is `custom`; must be omitted for preset billing periods.", "enum": [ "day", "week", "month", "year" ] }, "CustomFieldRequestType": { "type": "string", "description": "The type of the field.", "enum": [ "text", "checkbox" ] }, "TextFieldConfig": { "type": "object", "properties": { "max_length": { "type": "number", "description": "Maximum character length constraint for the input.", "example": 200 }, "min_length": { "type": "number", "description": "Minimum character length requirement for the input.", "example": 1 } } }, "CheckboxFieldConfig": { "type": "object", "properties": { "label": { "type": "string", "description": "The markdown text to display for the checkbox.", "example": "I agree to the [terms and conditions](https://example.com/terms)" } } }, "CustomFieldRequestEntity": { "type": "object", "properties": { "type": { "example": "text", "$ref": "#/components/schemas/CustomFieldRequestType" }, "key": { "type": "string", "description": "Unique key for custom field. Must be unique to this field, alphanumeric, and up to 200 characters.", "example": "companyName", "maxLength": 200 }, "label": { "type": "string", "description": "The label for the field, displayed to the customer, up to 50 characters.", "example": "Company Name", "maxLength": 50 }, "optional": { "type": "boolean", "description": "Whether the customer is required to complete the field. Defaults to `false`" }, "text": { "description": "Configuration for text field type.", "allOf": [ { "$ref": "#/components/schemas/TextFieldConfig" } ] }, "checkbox": { "description": "Configuration for checkbox field type.", "allOf": [ { "$ref": "#/components/schemas/CheckboxFieldConfig" } ] } }, "required": [ "type", "key", "label" ] }, "CreateProductRequestEntity": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the product" }, "description": { "type": "string", "description": "Description of the product" }, "image_url": { "type": "string", "description": "URL of the product image", "example": "https://picsum.photos/200/300" }, "image_urls": { "description": "Ordered list of product image URLs (max 8). The first entry is the cover image; when provided it takes precedence over image_url.", "example": [ "https://picsum.photos/200/300", "https://picsum.photos/200/301" ], "type": "array", "items": { "type": "string" } }, "price": { "type": "integer", "description": "The price of the product in cents. Must be 0 (free product) or at least 100 (one whole unit of the currency).", "example": 400 }, "currency": { "example": "USD", "$ref": "#/components/schemas/ProductCurrency" }, "billing_type": { "example": "recurring", "$ref": "#/components/schemas/ProductRequestBillingType" }, "billing_period": { "example": "every-month", "$ref": "#/components/schemas/ProductRequestBillingPeriod" }, "recurring_interval": { "example": "week", "$ref": "#/components/schemas/ProductRequestRecurringInterval" }, "recurring_interval_count": { "type": "integer", "description": "Number of `recurring_interval` units per billing cycle. Required when `billing_period` is `custom`. Bounds: day 1–365, week 1–52, month 1–24, year 1–3.", "example": 1 }, "tax_mode": { "example": "inclusive", "$ref": "#/components/schemas/TaxMode" }, "tax_category": { "example": "saas", "$ref": "#/components/schemas/TaxCategory" }, "pay_what_you_want": { "type": "boolean", "description": "Enable pay-what-you-want pricing: the customer chooses the amount at checkout. The `price` field acts as the minimum the customer must pay. Only supported for one-time payment products.", "example": false }, "suggested_price": { "type": "integer", "description": "Suggested amount in cents, pre-filled at checkout when pay_what_you_want is enabled. Must be greater than or equal to `price` (the minimum). Ignored when pay_what_you_want is disabled.", "example": 1500 }, "default_success_url": { "type": "string", "description": "The URL to which the user will be redirected after successfull payment.", "example": "https://example.com/?status=successful" }, "custom_fields": { "description": "Collect additional information from your customer using custom fields during checkout. Up to 3 fields are supported.", "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldRequestEntity" } }, "custom_field": { "description": "DEPRECATED: Use `custom_fields` instead. Collect additional information from your customer using custom fields during checkout. Up to 3 fields are supported.", "deprecated": true, "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldRequestEntity" } }, "abandoned_cart_recovery_enabled": { "type": "boolean", "description": "Enable abandoned cart recovery for this product", "default": false } }, "required": [ "name", "description", "price", "currency", "billing_type" ] }, "UpdateProductRequestEntity": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the product" }, "description": { "type": "string", "description": "Description of the product" }, "image_url": { "type": "string", "description": "URL of the product image" }, "image_urls": { "description": "Ordered list of product image URLs (max 8). The first entry is the cover image; when provided it takes precedence over image_url. An empty list — or an explicit `null` — removes all images. Omit to leave the gallery unchanged.", "type": "array", "items": { "type": "string" } }, "default_success_url": { "type": "string", "description": "Redirect URL after successful payment." }, "price": { "type": "integer", "description": "The price of the product in cents. Must be 0 (free product) or at least 100 (one whole unit of the currency)." }, "currency": { "example": "USD", "$ref": "#/components/schemas/ProductCurrency" }, "billing_type": { "example": "recurring", "$ref": "#/components/schemas/ProductRequestBillingType" }, "billing_period": { "example": "every-month", "$ref": "#/components/schemas/ProductRequestBillingPeriod" }, "recurring_interval": { "example": "week", "$ref": "#/components/schemas/ProductRequestRecurringInterval" }, "recurring_interval_count": { "type": "integer", "description": "Number of `recurring_interval` units per billing cycle. Required when `billing_period` is `custom`. Bounds: day 1–365, week 1–52, month 1–24, year 1–3." }, "tax_mode": { "example": "inclusive", "$ref": "#/components/schemas/TaxMode" }, "pay_what_you_want": { "type": "boolean", "description": "Enable pay-what-you-want pricing (one-time only)." }, "suggested_price": { "type": "integer", "description": "Suggested amount in cents when pay_what_you_want is enabled. Omit to leave unchanged; send `null` to clear it." } } }, "CustomerEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object." }, "mode": { "$ref": "#/components/schemas/EnvironmentMode" }, "object": { "type": "string", "description": "String representing the object’s type. Objects of the same type share the same value." }, "email": { "type": "string", "description": "Customer email address.", "example": "user@example.com" }, "name": { "type": "string", "description": "Customer name.", "example": "John Doe", "nullable": true }, "metadata": { "type": "object", "description": "Additional metadata associated with the customer.", "example": { "key": "value" }, "additionalProperties": true, "nullable": true }, "country": { "type": "string", "description": "The ISO 3166-1 alpha-2 country code for the customer.", "example": "US", "pattern": "^[A-Z]{2}$", "nullable": true }, "created_at": { "format": "date-time", "type": "string", "description": "Creation date of the customer", "example": "2023-01-01T00:00:00Z" }, "updated_at": { "format": "date-time", "type": "string", "description": "Last updated date of the customer", "example": "2023-01-01T00:00:00Z" } }, "required": [ "id", "mode", "object", "email", "country", "created_at", "updated_at" ] }, "CustomerListEntity": { "type": "object", "properties": { "items": { "description": "List of customer items", "items": { "$ref": "#/components/schemas/CustomerEntity" }, "type": "array" }, "pagination": { "description": "Pagination details for the list", "allOf": [ { "$ref": "#/components/schemas/PaginationEntity" } ] } }, "required": [ "items", "pagination" ] }, "OrderStatus": { "type": "string", "description": "Current status of the order.", "enum": [ "pending", "paid" ] }, "OrderType": { "type": "string", "description": "The type of order. This can specify whether it's a regular purchase, subscription, etc.", "enum": [ "recurring", "onetime" ] }, "OrderEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object." }, "mode": { "$ref": "#/components/schemas/EnvironmentMode" }, "object": { "type": "string", "description": "String representing the object's type. Objects of the same type share the same value." }, "customer": { "type": "string", "description": "The customer who placed the order.", "nullable": true }, "product": { "type": "string", "description": "The product associated with the order." }, "transaction": { "type": "string", "description": "The transaction ID of the order", "example": "tx_1234567890", "nullable": true }, "discount": { "type": "string", "description": "The discount ID of the order", "example": "dis_1234567890", "nullable": true }, "amount": { "type": "number", "description": "The total amount of the order in cents. 1000 = $10.00", "example": 2000 }, "sub_total": { "type": "number", "description": "The subtotal of the order in cents. 1000 = $10.00", "example": 1800 }, "tax_amount": { "type": "number", "description": "The tax amount of the order in cents. 1000 = $10.00", "example": 200 }, "discount_amount": { "type": "number", "description": "The discount amount of the order in cents. 1000 = $10.00", "example": 100 }, "amount_due": { "type": "number", "description": "The amount due for the order in cents. 1000 = $10.00", "example": 1900 }, "amount_paid": { "type": "number", "description": "The amount paid for the order in cents. 1000 = $10.00", "example": 1900 }, "currency": { "type": "string", "description": "Three-letter ISO currency code, in uppercase. Must be a supported currency.", "example": "USD" }, "fx_amount": { "type": "number", "description": "The amount in the foreign currency, if applicable.", "example": 15, "nullable": true }, "fx_currency": { "type": "string", "description": "Three-letter ISO code of the foreign currency, if applicable.", "example": "EUR", "nullable": true }, "fx_rate": { "type": "number", "description": "The exchange rate used for converting between currencies, if applicable.", "example": 1.2, "nullable": true }, "status": { "example": "pending", "$ref": "#/components/schemas/OrderStatus" }, "type": { "example": "recurring", "$ref": "#/components/schemas/OrderType" }, "affiliate": { "type": "string", "description": "The affiliate associated with the order, if applicable.", "nullable": true }, "created_at": { "format": "date-time", "type": "string", "description": "Creation date of the order", "example": "2023-09-13T00:00:00Z" }, "updated_at": { "format": "date-time", "type": "string", "description": "Last updated date of the order", "example": "2023-09-13T00:00:00Z" } }, "required": [ "id", "mode", "object", "product", "amount", "currency", "status", "type", "created_at", "updated_at" ] }, "OrderListEntity": { "type": "object", "properties": { "items": { "description": "List of order items", "items": { "$ref": "#/components/schemas/OrderEntity" }, "type": "array" }, "pagination": { "description": "Pagination details for the list", "allOf": [ { "$ref": "#/components/schemas/PaginationEntity" } ] } }, "required": [ "items", "pagination" ] }, "SubscriptionItemEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object." }, "mode": { "$ref": "#/components/schemas/EnvironmentMode" }, "object": { "type": "string", "description": "String representing the object’s type. Objects of the same type share the same value." }, "product_id": { "type": "string", "description": "The ID of the product associated with the subscription item." }, "price_id": { "type": "string", "description": "The ID of the price associated with the subscription item." }, "units": { "type": "number", "description": "The number of units for the subscription item.", "nullable": true } }, "required": [ "id", "mode", "object" ] }, "SubscriptionCollectionMethod": { "type": "string", "description": "The method used for collecting payments for the subscription.", "enum": [ "charge_automatically" ] }, "SubscriptionStatus": { "type": "string", "description": "The current status of the subscription.", "enum": [ "active", "canceled", "unpaid", "paused", "trialing", "scheduled_cancel", "past_due" ] }, "TransactionType": { "type": "string", "description": "The type of transaction. payment(one time payments) and invoice(subscription)", "enum": [ "payment", "invoice" ] }, "TransactionStatus": { "type": "string", "description": "Status of the transaction.", "enum": [ "pending", "paid", "refunded", "partialRefund", "chargedBack", "uncollectible", "declined", "canceled", "void" ] }, "TransactionEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object." }, "mode": { "$ref": "#/components/schemas/EnvironmentMode" }, "object": { "type": "string", "description": "String representing the object's type. Objects of the same type share the same value.", "example": "transaction" }, "amount": { "type": "number", "description": "The transaction amount in cents. 1000 = $10.00", "example": 2000 }, "amount_paid": { "type": "number", "description": "The amount the customer paid in cents. 1000 = $10.00", "example": 2000, "nullable": true }, "discount_amount": { "type": "number", "description": "The discount amount in cents. 1000 = $10.00", "example": 2000, "nullable": true }, "currency": { "type": "string", "description": "Three-letter ISO currency code, in uppercase. Must be a supported currency.", "example": "USD" }, "type": { "$ref": "#/components/schemas/TransactionType" }, "tax_country": { "type": "string", "description": "The ISO alpha-2 country code where tax is collected.", "example": "US", "pattern": "^[A-Z]{2}$", "nullable": true }, "tax_amount": { "type": "number", "description": "The sale tax amount in cents. 1000 = $10.00", "example": 2000, "nullable": true }, "status": { "$ref": "#/components/schemas/TransactionStatus" }, "refunded_amount": { "type": "number", "description": "The amount that has been refunded in cents. 1000 = $10.00", "example": 2000, "nullable": true }, "order": { "type": "string", "description": "The order associated with the transaction.", "nullable": true }, "subscription": { "type": "string", "description": "The subscription associated with the transaction.", "nullable": true }, "customer": { "type": "string", "description": "The customer associated with the transaction.", "nullable": true }, "description": { "type": "string", "description": "The description of the transaction." }, "period_start": { "type": "number", "description": "Start period for the invoice as timestamp" }, "period_end": { "type": "number", "description": "End period for the invoice as timestamp" }, "created_at": { "type": "number", "description": "Creation date of the order as timestamp" } }, "required": [ "id", "mode", "object", "amount", "currency", "type", "status", "created_at" ] }, "SubscriptionEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object." }, "mode": { "$ref": "#/components/schemas/EnvironmentMode" }, "object": { "type": "string", "description": "String representing the object's type. Objects of the same type share the same value.", "example": "subscription" }, "product": { "description": "The product associated with the subscription.", "oneOf": [ { "$ref": "#/components/schemas/ProductEntity" }, { "type": "string" } ] }, "customer": { "description": "The customer who owns the subscription.", "oneOf": [ { "$ref": "#/components/schemas/CustomerEntity" }, { "type": "string" } ] }, "items": { "description": "Subscription items.", "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionItemEntity" } }, "collection_method": { "example": "charge_automatically", "$ref": "#/components/schemas/SubscriptionCollectionMethod" }, "status": { "example": "active", "$ref": "#/components/schemas/SubscriptionStatus" }, "last_transaction_id": { "type": "string", "description": "The ID of the last paid transaction.", "example": "tran_3e6Z6TzvHKdsjEgXnGDEp0" }, "last_transaction": { "description": "The last paid transaction.", "allOf": [ { "$ref": "#/components/schemas/TransactionEntity" } ] }, "last_transaction_date": { "format": "date-time", "type": "string", "description": "The date of the last paid transaction.", "example": "2024-09-12T12:34:56Z" }, "next_transaction_date": { "format": "date-time", "type": "string", "description": "The date when the next subscription transaction will be charged.", "example": "2024-09-12T12:34:56Z" }, "current_period_start_date": { "format": "date-time", "type": "string", "description": "The start date of the current subscription period.", "example": "2024-09-12T12:34:56Z" }, "current_period_end_date": { "format": "date-time", "type": "string", "description": "The end date of the current subscription period.", "example": "2024-09-12T12:34:56Z" }, "canceled_at": { "type": "string", "description": "The date and time when the subscription was canceled, if applicable.", "example": "2024-09-12T12:34:56Z", "format": "date-time", "nullable": true }, "created_at": { "format": "date-time", "type": "string", "description": "The date and time when the subscription was created.", "example": "2024-01-01T00:00:00Z" }, "updated_at": { "type": "string", "description": "The date and time when the subscription was last updated.", "example": "2024-09-12T12:34:56Z", "format": "date-time" }, "discount": { "type": "object", "description": "The discount applied to the subscription, if any.", "properties": { "id": { "type": "string", "description": "The unique identifier of the discount (e.g. dis_...).", "example": "dis_3e6Z6TzvHKdsjEgXnGDEp0" }, "discountCode": { "type": "string", "description": "The discount code applied to the subscription.", "example": "HOLIDAY2024" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "percentage", "fixed" ] }, "amount": { "type": "number" }, "duration": { "type": "string", "enum": [ "forever", "once", "repeating" ] }, "durationInMonths": { "type": "number" } } }, "metadata": { "type": "object", "description": "Metadata for the subscription in the form of key-value pairs.", "example": { "userId": "user_123", "plan": "pro" }, "additionalProperties": true } }, "required": [ "id", "mode", "object", "product", "customer", "collection_method", "status", "created_at", "updated_at" ] }, "SubscriptionListEntity": { "type": "object", "properties": { "items": { "description": "List of subscription items", "items": { "$ref": "#/components/schemas/SubscriptionEntity" }, "type": "array" }, "pagination": { "description": "Pagination details for the list", "allOf": [ { "$ref": "#/components/schemas/PaginationEntity" } ] } }, "required": [ "items", "pagination" ] }, "LicenseStatus": { "type": "string", "description": "The current status of the license key.", "enum": [ "inactive", "active", "expired", "disabled" ] }, "LicenseInstanceEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object." }, "mode": { "$ref": "#/components/schemas/EnvironmentMode" }, "object": { "type": "string", "description": "A string representing the object’s type. Objects of the same type share the same value.", "example": "license-instance" }, "name": { "type": "string", "description": "The name of the license instance.", "example": "My Customer License Instance" }, "status": { "type": "string", "description": "The status of the license instance.", "enum": [ "active", "deactivated" ], "example": "active" }, "created_at": { "format": "date-time", "type": "string", "description": "The creation date of the license instance.", "example": "2023-09-13T00:00:00Z" } }, "required": [ "id", "mode", "object", "name", "status", "created_at" ] }, "LicenseEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object." }, "mode": { "$ref": "#/components/schemas/EnvironmentMode" }, "object": { "type": "string", "description": "A string representing the object's type. Objects of the same type share the same value." }, "product_id": { "type": "string", "description": "The ID of the product this license belongs to.", "example": "prod_abc123" }, "status": { "example": "active", "$ref": "#/components/schemas/LicenseStatus" }, "key": { "type": "string", "description": "The license key.", "example": "ABC123-XYZ456-XYZ456-XYZ456" }, "activation": { "type": "number", "description": "The number of instances that this license key was activated.", "example": 5 }, "activation_limit": { "type": "number", "description": "The activation limit. Null if activations are unlimited.", "example": 1, "nullable": true }, "expires_at": { "type": "string", "description": "The date the license key expires. Null if it does not have an expiration date.", "example": "2023-09-13T00:00:00Z", "format": "date-time", "nullable": true }, "created_at": { "format": "date-time", "type": "string", "description": "The creation date of the license key.", "example": "2023-09-13T00:00:00Z" }, "instance": { "description": "Associated license instances.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/LicenseInstanceEntity" } ] } }, "required": [ "id", "mode", "object", "product_id", "status", "key", "activation", "created_at" ] }, "LicenseListEntity": { "type": "object", "properties": { "items": { "description": "List of license items", "items": { "$ref": "#/components/schemas/LicenseEntity" }, "type": "array" }, "pagination": { "description": "Pagination details for the list", "allOf": [ { "$ref": "#/components/schemas/PaginationEntity" } ] } }, "required": [ "items", "pagination" ] }, "CreateCustomerRequestEntity": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address of the customer.", "example": "john@example.com" }, "name": { "type": "string", "description": "The full name of the customer.", "example": "John Doe" }, "metadata": { "type": "object", "description": "Additional metadata for the customer.", "example": { "key": "value" }, "additionalProperties": true } }, "required": [ "email", "name" ] }, "UpdateCustomerRequestEntity": { "type": "object", "properties": { "customer_id": { "type": "string", "description": "The ID of the customer to update.", "example": "cust_abc123" }, "name": { "type": "string", "description": "The full name of the customer.", "example": "John Doe" }, "metadata": { "type": "object", "description": "Additional metadata for the customer. Omit to leave unchanged; send `null` to clear it.", "example": { "key": "value" }, "additionalProperties": true } }, "required": [ "customer_id" ] }, "CreateCustomerPortalLinkRequestEntity": { "type": "object", "properties": { "customer_id": { "type": "string", "description": "Unique identifier of the customer." } }, "required": [ "customer_id" ] }, "CustomerLinksEntity": { "type": "object", "properties": { "customer_portal_link": { "type": "string", "description": "Customer portal link." } }, "required": [ "customer_portal_link" ] }, "CancelSubscriptionRequestEntity": { "type": "object", "properties": { "mode": { "type": "string", "description": "The mode of cancellation (immediate or scheduled), default can be configured in the store billing settings.", "enum": [ "immediate", "scheduled" ], "example": "immediate" }, "onExecute": { "type": "string", "description": "The action to execute when canceling (cancel or pause) when mode is scheduled, ignored when mode is immediate or not provided", "enum": [ "cancel", "pause" ], "example": "cancel" } } }, "UpsertSubscriptionItemEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the item to update." }, "product_id": { "type": "string", "description": "The ID of the product associated with the subscription item." }, "price_id": { "type": "string", "description": "The ID of the price associated with the subscription item." }, "units": { "type": "number", "description": "The number of units for the subscription item." } } }, "UpdateSubscriptionRequestEntity": { "type": "object", "properties": { "items": { "description": "List of subscription items to update/create. If no item ID is provided, the item will be created.", "type": "array", "items": { "$ref": "#/components/schemas/UpsertSubscriptionItemEntity" } }, "update_behavior": { "type": "string", "description": "The update behavior for the subscription (defaults to proration)", "enum": [ "proration-charge-immediately", "proration-charge", "proration-none" ], "default": "proration-charge" } } }, "UpgradeSubscriptionRequestEntity": { "type": "object", "properties": { "product_id": { "type": "string", "description": "The ID of the product to upgrade to", "example": "prod_123" }, "update_behavior": { "type": "string", "description": "The update behavior for the subscription (defaults to proration-charge-immediately)", "enum": [ "proration-charge-immediately", "proration-charge", "proration-none" ], "default": "proration-charge-immediately" } }, "required": [ "product_id" ] }, "FeatureFileEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the file.", "example": "file_abc123" }, "file_name": { "type": "string", "description": "The name of the file.", "example": "ebook.pdf" }, "url": { "type": "string", "description": "The URL to download the file.", "example": "https://storage.creem.io/files/ebook.pdf" }, "type": { "type": "string", "description": "The MIME type of the file.", "example": "application/pdf" }, "size": { "type": "number", "description": "The size of the file in bytes.", "example": 1024000 } }, "required": [ "id", "file_name", "url", "type", "size" ] }, "FileFeatureEntity": { "type": "object", "properties": { "files": { "description": "List of downloadable files.", "type": "array", "items": { "$ref": "#/components/schemas/FeatureFileEntity" } } }, "required": [ "files" ] }, "CustomerCreditsFeatureEntity": { "type": "object", "properties": { "amount": { "type": "string", "description": "The number of credits to grant. String to preserve BigInt precision.", "example": "100" }, "unit_label": { "type": "string", "description": "Optional label for the credit unit (e.g. \"tokens\", \"credits\").", "example": "tokens", "nullable": true }, "bucket_name": { "type": "string", "description": "The customer-credit bucket this grant funds — the `name` of the customer's credit account. Set it to a meter bucket (e.g. \"images\") so the credits fund a per-unit metered price; otherwise they land in `default` and metered usage cannot spend them. Distinct from `unit_label`, which is only a display label. On UPDATE the field is tri-state: OMIT it to leave the stored bucket unchanged, send `null` to clear it to the shared `default` wallet, or send a name to set it. On CREATE, omitted or null both mean `default`. A present-but-blank value is rejected.", "example": "images", "nullable": true } }, "required": [ "amount" ] }, "ProductFeatureEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the feature.", "example": "feat_abc123", "nullable": true }, "description": { "type": "string", "description": "A brief description of the feature.", "example": "Get access to the full course materials.", "nullable": true }, "type": { "example": "licenseKey", "nullable": true, "$ref": "#/components/schemas/ProductFeatureType" }, "private_note": { "type": "string", "description": "Private note from the seller. This is only visible to the customer after purchase.", "example": "Thank you for your purchase! Here is your access code: XYZ123", "nullable": true }, "file": { "description": "File feature data containing downloadable files.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/FileFeatureEntity" } ] }, "license_key": { "description": "License key issued for the order.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/LicenseEntity" } ] }, "customer_credits": { "description": "Customer credits feature data.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CustomerCreditsFeatureEntity" } ] }, "license": { "description": "DEPRECATED: Use `license_key` instead. License key issued for the order.", "nullable": true, "deprecated": true, "allOf": [ { "$ref": "#/components/schemas/LicenseEntity" } ] } } }, "CheckoutEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object." }, "mode": { "$ref": "#/components/schemas/EnvironmentMode" }, "object": { "type": "string", "description": "String representing the object's type. Objects of the same type share the same value." }, "status": { "type": "string", "description": "Status of the checkout.", "enum": [ "pending", "processing", "completed", "expired" ], "example": "completed" }, "request_id": { "type": "string", "description": "Identify and track each checkout request." }, "product": { "description": "The product associated with the checkout session.", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/ProductEntity" } ] }, "units": { "type": "number", "description": "The number of units for the of the product.", "default": 1 }, "custom_price": { "type": "integer", "description": "The per-unit price override (in cents, product currency) this checkout was created with. Only present when the checkout was created with a custom_price. One-time payment products only.", "example": 1500 }, "order": { "description": "The order associated with the checkout session.", "allOf": [ { "$ref": "#/components/schemas/OrderEntity" } ] }, "subscription": { "description": "The subscription associated with the checkout session.", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/SubscriptionEntity" } ] }, "customer": { "description": "The customer associated with the checkout session.", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/CustomerEntity" } ] }, "custom_fields": { "description": "Additional information collected from your customer during the checkout process.", "type": "array", "items": { "$ref": "#/components/schemas/CustomField" } }, "checkout_url": { "type": "string", "description": "The URL to which the customer will be redirected to complete the payment." }, "success_url": { "type": "string", "description": "The URL to which the user will be redirected after the checkout process is completed.", "example": "https://example.com/return", "nullable": true }, "license_keys": { "description": "License keys issued for the order.", "type": "array", "items": { "$ref": "#/components/schemas/LicenseEntity" } }, "feature": { "description": "DEPRECATED: Use `license_keys` instead. Features issued for the order.", "deprecated": true, "type": "array", "items": { "$ref": "#/components/schemas/ProductFeatureEntity" } }, "metadata": { "type": "object", "description": "Metadata for the checkout in the form of key-value pairs", "example": { "userId": "user_123", "visitCount": 42, "lastVisit": "2023-04-01" }, "additionalProperties": true }, "discount": { "type": "object", "description": "The discount applied to the checkout, if any.", "properties": { "id": { "type": "string", "description": "The unique identifier of the discount (e.g. dis_...).", "example": "dis_3e6Z6TzvHKdsjEgXnGDEp0" }, "discountCode": { "type": "string", "description": "The discount code applied to the checkout.", "example": "HOLIDAY2024" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "percentage", "fixed" ] }, "amount": { "type": "number" }, "duration": { "type": "string", "enum": [ "forever", "once", "repeating" ] }, "durationInMonths": { "type": "number" } } } }, "required": [ "id", "mode", "object", "status", "product" ] }, "CustomerRequestEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the customer. You may specify only one of these parameters: id or email.", "example": "cust_1234567890" }, "email": { "type": "string", "description": "Customer email address. You may only specify one of these parameters: id, email.", "example": "user@example.com" }, "name": { "type": "string", "description": "Customer full name. Used to prefill the name field on the checkout page.", "example": "John Doe" } } }, "CreateCheckoutRequest": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identify and track each checkout request." }, "product_id": { "type": "string", "description": "The ID of the product associated with the checkout session.", "example": "prod_1234567890" }, "units": { "type": "number", "description": "The number of units for the order.", "example": 1 }, "custom_price": { "type": "integer", "description": "Override the unit price of the product for this checkout session, in cents (e.g. 1500 = $15.00). The product currency is used, and the amount is per unit: with `units: 3` and `custom_price: 1500` the customer pays 4500. Must be between 100 (one whole unit of the currency) and 99999999. Only supported for one-time payment products. Use this for dynamic pricing models such as pay-what-you-want, donations, or amounts calculated by your application.", "example": 1500 }, "discount_code": { "type": "string", "description": "Prefill the checkout session with a discount code.", "example": "SUMMER2024" }, "affiliate_code": { "type": "string", "description": "Attribute this checkout to an affiliate using the affiliate's referral code (the unique code from their referral link). Use this to manually credit a sale to a specific affiliate when you already hold their code on your backend, instead of relying on referral-link clicks/cookies. The code must belong to an active affiliate of this store; an invalid, inactive, or foreign-store code is rejected.", "example": "aff_abc123" }, "customer": { "description": "Customer data for checkout session. This will prefill the customer info on the checkout page.", "allOf": [ { "$ref": "#/components/schemas/CustomerRequestEntity" } ] }, "custom_fields": { "description": "Collect additional information from your customer using custom fields. Up to 3 fields are supported.", "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldRequestEntity" } }, "custom_field": { "description": "DEPRECATED: Use `custom_fields` instead. Collect additional information from your customer using custom fields. Up to 3 fields are supported.", "deprecated": true, "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldRequestEntity" } }, "success_url": { "type": "string", "description": "The URL to which the user will be redirected after the checkout process is completed." }, "metadata": { "type": "object", "description": "Metadata for the checkout in the form of key-value pairs", "example": { "userId": "user_123", "visitCount": 42, "lastVisit": "2023-04-01" }, "additionalProperties": true } }, "required": [ "product_id" ] }, "ActivateLicenseRequestEntity": { "type": "object", "properties": { "key": { "type": "string", "description": "The license key to activate." }, "instance_name": { "type": "string", "description": "A label for the new instance to identify it in Creem." } }, "required": [ "key", "instance_name" ] }, "DeactivateLicenseRequestEntity": { "type": "object", "properties": { "key": { "type": "string", "description": "The license key to deactivate." }, "instance_id": { "type": "string", "description": "Id of the instance to deactivate." } }, "required": [ "key", "instance_id" ] }, "ValidateLicenseRequestEntity": { "type": "object", "properties": { "key": { "type": "string", "description": "The license key to validate." }, "instance_id": { "type": "string", "description": "Id of the instance to validate." } }, "required": [ "key", "instance_id" ] }, "LicenseInstanceListEntity": { "type": "object", "properties": { "items": { "description": "List of license instance items", "items": { "$ref": "#/components/schemas/LicenseInstanceEntity" }, "type": "array" }, "pagination": { "description": "Pagination details for the list", "allOf": [ { "$ref": "#/components/schemas/PaginationEntity" } ] } }, "required": [ "items", "pagination" ] }, "DiscountEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object." }, "mode": { "$ref": "#/components/schemas/EnvironmentMode" }, "object": { "type": "string", "description": "A string representing the object’s type. Objects of the same type share the same value.", "example": "discount" }, "status": { "type": "string", "description": "The status of the discount (e.g., active, inactive).", "enum": [ "deleted", "active", "draft", "expired", "scheduled" ], "example": "active" }, "name": { "type": "string", "description": "The name of the discount.", "example": "Holiday Sale" }, "code": { "type": "string", "description": "The discount code. A unique identifier for the discount.", "example": "HOLIDAY2024" }, "type": { "type": "string", "description": "The type of the discount, either \"percentage\" or \"fixed\".", "enum": [ "percentage", "fixed" ], "example": "percentage" }, "amount": { "type": "number", "description": "The amount of the discount. Can be a percentage or a fixed amount.", "example": 20 }, "currency": { "type": "string", "description": "The currency of the discount. Only required if type is \"fixed\".", "example": "USD" }, "percentage": { "type": "number", "description": "The percentage of the discount. Only applicable if type is \"percentage\".", "example": 15 }, "expiry_date": { "format": "date-time", "type": "string", "description": "The expiry date of the discount.", "example": "2024-12-31T23:59:59Z" }, "max_redemptions": { "type": "number", "description": "The maximum number of redemptions allowed for the discount.", "example": 100 }, "duration": { "type": "string", "description": "The duration type for the discount.", "enum": [ "forever", "once", "repeating" ], "example": "repeating" }, "duration_in_months": { "type": "number", "description": "The number of months the discount is valid for. Only applicable if the duration is \"repeating\" and the product is a subscription.", "example": 6 }, "applies_to_products": { "description": "The list of product IDs to which this discount applies.", "example": [ "prod_123", "prod_456" ], "type": "array", "items": { "type": "string" } }, "redeem_count": { "type": "number", "description": "The number of times this discount has been redeemed.", "example": 15 } }, "required": [ "id", "mode", "object", "status", "name", "code", "type" ] }, "DiscountListEntity": { "type": "object", "properties": { "items": { "description": "List of discount items", "items": { "$ref": "#/components/schemas/DiscountEntity" }, "type": "array" }, "pagination": { "description": "Pagination details for the list", "allOf": [ { "$ref": "#/components/schemas/PaginationEntity" } ] } }, "required": [ "items", "pagination" ] }, "DiscountType": { "type": "string", "description": "The type of the discount, either \"percentage\" or \"fixed\".", "enum": [ "percentage", "fixed" ] }, "CouponDurationType": { "type": "string", "description": "The duration type for the discount.", "enum": [ "forever", "once", "repeating" ] }, "CreateDiscountRequestEntity": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the discount.", "example": "Holiday Sale" }, "code": { "type": "string", "description": "Optional discount code. If left empty, a code will be generated.", "example": "HOLIDAY2024" }, "type": { "$ref": "#/components/schemas/DiscountType" }, "amount": { "type": "number", "description": "The fixed value for the discount. Only applicable if the type is \"fixed\".", "example": 20 }, "currency": { "type": "string", "description": "The currency of the discount. Only required if type is \"fixed\".", "example": "USD" }, "percentage": { "type": "number", "description": "The percentage value for the discount. Only applicable if the type is \"percentage\".", "example": 15 }, "expiry_date": { "format": "date-time", "type": "string", "description": "The expiry date of the discount.", "example": "2024-12-31T23:59:59Z" }, "max_redemptions": { "type": "number", "description": "The maximum number of redemptions for the discount.", "example": 100 }, "duration": { "example": "repeating", "$ref": "#/components/schemas/CouponDurationType" }, "duration_in_months": { "type": "number", "description": "The number of months the discount is valid for. Only applicable if the duration is \"repeating\" and the product is a subscription.", "example": 6 }, "applies_to_products": { "description": "The list of product IDs to which this discount applies.", "example": [ "prod_123", "prod_456" ], "type": "array", "items": { "type": "string" } } }, "required": [ "name", "type", "duration", "applies_to_products" ] }, "TransactionListEntity": { "type": "object", "properties": { "items": { "description": "List of transactions items", "items": { "$ref": "#/components/schemas/TransactionEntity" }, "type": "array" }, "pagination": { "description": "Pagination details for the list", "allOf": [ { "$ref": "#/components/schemas/PaginationEntity" } ] } }, "required": [ "items", "pagination" ] }, "StatsMetricTotalsEntity": { "type": "object", "properties": { "totalProducts": { "type": "number", "description": "Total number of products in the store", "example": 12 }, "totalSubscriptions": { "type": "number", "description": "Total number of subscriptions within the queried date range", "example": 48 }, "totalCustomers": { "type": "number", "description": "Total number of customers within the queried date range", "example": 35 }, "totalPayments": { "type": "number", "description": "Total number of payments within the queried date range", "example": 62 }, "activeSubscriptions": { "type": "number", "description": "Number of currently active subscriptions", "example": 21 }, "totalRevenue": { "type": "number", "description": "Total gross revenue in cents within the queried date range", "example": 553939 }, "totalNetRevenue": { "type": "number", "description": "Total net revenue in cents within the queried date range (after fees and taxes)", "example": 478094 }, "netMonthlyRecurringRevenue": { "type": "number", "description": "Net monthly recurring revenue in cents (after estimated fees)", "example": 89500 }, "monthlyRecurringRevenue": { "type": "number", "description": "Gross monthly recurring revenue in cents", "example": 94200 } }, "required": [ "totalProducts", "totalSubscriptions", "totalCustomers", "totalPayments", "activeSubscriptions", "totalRevenue", "totalNetRevenue", "netMonthlyRecurringRevenue", "monthlyRecurringRevenue" ] }, "StatsMetricPeriodEntity": { "type": "object", "properties": { "timestamp": { "type": "number", "description": "Start of the period as a Unix timestamp in milliseconds (e.g. Monday of that week for weekly intervals)", "example": 1765152000000 }, "grossRevenue": { "type": "number", "description": "Gross revenue in cents for this period", "example": 125958 }, "netRevenue": { "type": "number", "description": "Net revenue in cents for this period (after fees and taxes)", "example": 122173 } }, "required": [ "timestamp", "grossRevenue", "netRevenue" ] }, "StatsSummaryEntity": { "type": "object", "properties": { "totals": { "description": "Aggregated totals for the queried date range", "allOf": [ { "$ref": "#/components/schemas/StatsMetricTotalsEntity" } ] }, "periods": { "description": "Time-series data points grouped by the requested interval. Only present when interval, startDate, and endDate are provided.", "example": [ { "timestamp": 1763337600000, "grossRevenue": 2999, "netRevenue": 2909 }, { "timestamp": 1763942400000, "grossRevenue": 32989, "netRevenue": 31998 }, { "timestamp": 1764547200000, "grossRevenue": 47984, "netRevenue": 46542 }, { "timestamp": 1765152000000, "grossRevenue": 125958, "netRevenue": 122173 }, { "timestamp": 1765756800000, "grossRevenue": 343968, "netRevenue": 278372 }, { "timestamp": 1766361600000, "grossRevenue": 0, "netRevenue": 0 }, { "timestamp": 1766966400000, "grossRevenue": 0, "netRevenue": 0 }, { "timestamp": 1767571200000, "grossRevenue": 225240, "netRevenue": 192096 } ], "type": "array", "items": { "$ref": "#/components/schemas/StatsMetricPeriodEntity" } } }, "required": [ "totals" ] }, "ScreenPromptRequest": { "type": "object", "properties": { "prompt": { "type": "string", "description": "The text prompt to evaluate against content policies." }, "external_id": { "type": "string", "description": "An optional identifier to associate this request with." } }, "required": [ "prompt" ] }, "UsageEntity": { "type": "object", "properties": { "units": { "type": "number", "description": "Number of units consumed by this call." } }, "required": [ "units" ] }, "ScreenPromptResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the moderation result." }, "object": { "type": "string", "description": "Object type.", "example": "moderation_result" }, "prompt": { "type": "string", "description": "The prompt that was screened." }, "external_id": { "type": "string", "description": "The external identifier provided in the request." }, "decision": { "type": "string", "description": "The moderation decision.", "enum": [ "allow", "deny", "flag" ] }, "usage": { "description": "Usage information for this call.", "allOf": [ { "$ref": "#/components/schemas/UsageEntity" } ] } }, "required": [ "id", "object", "prompt", "decision", "usage" ] }, "CreateRefundRequestEntity": { "type": "object", "properties": { "transaction_id": { "type": "string", "description": "The unique identifier of the transaction to refund in full.", "example": "tran_1234567890" } }, "required": [ "transaction_id" ] }, "RefundStatus": { "type": "string", "description": "Status of the refund. `pending` and `requiresAction` represent non-terminal provider processing states.", "enum": [ "pending", "requiresAction", "succeeded", "failed", "canceled" ] }, "RefundResponseEntity": { "type": "object", "properties": { "status": { "example": "succeeded", "$ref": "#/components/schemas/RefundStatus" } }, "required": [ "status" ] }, "CreateAccountDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable name for the account", "example": "default", "default": "default" }, "customer_id": { "type": "string", "description": "The owner ID this account belongs to (e.g. customer ID)", "example": "cust_abc123" }, "unit_label": { "type": "string", "description": "Label for the unit of currency/credits", "example": "credits", "default": "credits" }, "initial_balance": { "type": "string", "description": "Seed the account with this many credits on creation", "example": "300" } }, "required": [ "customer_id" ] }, "AccountResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Account ID", "example": "cca_abc123" }, "store_id": { "type": "string", "description": "Store ID" }, "customer_id": { "type": "string", "description": "Owner ID", "example": "cust_abc123" }, "name": { "type": "string", "description": "Account name", "example": "default" }, "unit_label": { "type": "string", "description": "Unit label", "example": "credits" }, "status": { "type": "string", "description": "Account status", "enum": [ "active", "frozen", "closed" ] }, "created_at": { "type": "string", "description": "Creation timestamp" }, "updated_at": { "type": "string", "description": "Last update timestamp" } }, "required": [ "id", "store_id", "customer_id", "name", "unit_label", "status", "created_at", "updated_at" ] }, "AccountListResponseDto": { "type": "object", "properties": { "object": { "type": "string", "description": "Object type", "example": "list" }, "data": { "description": "Array of accounts", "type": "array", "items": { "$ref": "#/components/schemas/AccountResponseDto" } }, "has_more": { "type": "boolean", "description": "Whether more items exist beyond this page" } }, "required": [ "object", "data", "has_more" ] }, "BalanceResponseDto": { "type": "object", "properties": { "balance": { "type": "string", "description": "Current balance as string for bigint safety", "example": "5000" }, "updated_at": { "type": "string", "description": "Last update timestamp (present for projected balance)" }, "as_of": { "type": "string", "description": "Point-in-time the balance was computed at (present for at-time queries)" } }, "required": [ "balance" ] }, "EntryResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Entry ID", "example": "cce_abc123" }, "transaction_id": { "type": "string", "description": "Transaction ID", "example": "cct_abc123" }, "account_id": { "type": "string", "description": "Account ID", "example": "cca_abc123" }, "side": { "type": "string", "description": "Debit or credit side", "enum": [ "debit", "credit" ] }, "amount": { "type": "string", "description": "Amount as string for bigint safety", "example": "1000" }, "created_at": { "type": "string", "description": "Creation timestamp" } }, "required": [ "id", "transaction_id", "account_id", "side", "amount", "created_at" ] }, "EntryListResponseDto": { "type": "object", "properties": { "object": { "type": "string", "description": "Object type", "example": "list" }, "data": { "description": "Array of entries", "type": "array", "items": { "$ref": "#/components/schemas/EntryResponseDto" } }, "has_more": { "type": "boolean", "description": "Whether more items exist beyond this page" } }, "required": [ "object", "data", "has_more" ] }, "CustomerCreditsErrorDetailDto": { "type": "object", "properties": { "type": { "type": "string", "description": "Error category", "enum": [ "invalid_request_error", "api_error", "authentication_error", "rate_limit_error" ], "example": "invalid_request_error" }, "code": { "type": "string", "description": "Machine-readable error code", "example": "unbalanced_transaction", "nullable": true }, "message": { "type": "string", "description": "Human-readable error message", "example": "Total debits must equal total credits" }, "param": { "type": "string", "description": "The parameter related to the error, if applicable", "example": "entries", "nullable": true }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req_abc123def456" } }, "required": [ "type", "code", "message", "request_id" ] }, "CustomerCreditsErrorResponseDto": { "type": "object", "properties": { "error": { "description": "Error details", "allOf": [ { "$ref": "#/components/schemas/CustomerCreditsErrorDetailDto" } ] } }, "required": [ "error" ] }, "CreditDebitRequestDto": { "type": "object", "properties": { "amount": { "type": "string", "description": "Amount to credit or debit (string to support large numbers)", "example": "1000" }, "reference": { "type": "string", "description": "Your reference ID to link this transaction to an event in your system (e.g. order ID, campaign ID)", "example": "signup_bonus" }, "idempotency_key": { "type": "string", "description": "Idempotency key to prevent duplicate transactions", "example": "idem_abc123" } }, "required": [ "amount", "reference", "idempotency_key" ] }, "TransactionResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Transaction ID", "example": "cct_abc123" }, "store_id": { "type": "string", "description": "Store ID" }, "reference": { "type": "string", "description": "Reference string", "example": "order_xyz" }, "idempotency_key": { "type": "string", "description": "Idempotency key" }, "reversal_of": { "type": "string", "description": "ID of the transaction this reverses, if applicable", "example": "cct_abc123", "nullable": true }, "entries": { "description": "Transaction entries", "type": "array", "items": { "$ref": "#/components/schemas/EntryResponseDto" } }, "created_at": { "type": "string", "description": "Creation timestamp" } }, "required": [ "id", "store_id", "reference", "idempotency_key", "entries", "created_at" ] }, "ReverseTransactionRequestDto": { "type": "object", "properties": { "transaction_id": { "type": "string", "description": "ID of the transaction to reverse", "example": "cct_abc123" } }, "required": [ "transaction_id" ] }, "CreateAffiliateInviteRequestEntity": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address to send the affiliate invitation to.", "example": "partner@example.com" }, "name": { "type": "string", "description": "The display name of the affiliate being invited.", "example": "Jane Partner" }, "program_id": { "type": "string", "description": "The ID of the affiliate program to invite into. Optional: when omitted, the invitation falls back to the store's affiliate program. Provide this only if your store runs more than one program.", "example": "prog_1234567890", "nullable": true } }, "required": [ "email", "name" ] }, "AffiliateInviteEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object." }, "mode": { "$ref": "#/components/schemas/EnvironmentMode" }, "object": { "type": "string", "description": "String representing the object's type. Objects of the same type share the same value.", "example": "affiliate-invite" }, "email": { "type": "string", "description": "The email address the affiliate was invited with.", "example": "partner@example.com" }, "name": { "type": "string", "description": "The display name the affiliate was invited with.", "example": "Jane Partner", "nullable": true }, "status": { "type": "string", "description": "The lifecycle status of the invitation: `pending` while the invitee has not yet accepted, `accepted` once they have joined the program.", "example": "pending" }, "created_at": { "type": "number", "description": "Creation date of the invitation as a timestamp." } }, "required": [ "id", "mode", "object", "email", "status", "created_at" ] }, "AffiliateInviteListEntity": { "type": "object", "properties": { "items": { "description": "List of affiliate invitation items", "items": { "$ref": "#/components/schemas/AffiliateInviteEntity" }, "type": "array" }, "pagination": { "description": "Pagination details for the list", "allOf": [ { "$ref": "#/components/schemas/PaginationEntity" } ] } }, "required": [ "items", "pagination" ] }, "AffiliateEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object." }, "mode": { "$ref": "#/components/schemas/EnvironmentMode" }, "object": { "type": "string", "description": "String representing the object's type. Objects of the same type share the same value.", "example": "affiliate" }, "email": { "type": "string", "description": "The email address the affiliate was invited with.", "example": "partner@example.com" }, "name": { "type": "string", "description": "The display name of the affiliate, if set.", "example": "Jane Partner", "nullable": true }, "status": { "type": "string", "description": "The affiliate's status within your program, reflecting their membership standing: `active`, `pending` (awaiting approval), `rejected`, `suspended`, or `inactive` (left or removed). Invited-but-not-yet-joined affiliates are not returned by this endpoint.", "example": "active" }, "referral_code": { "type": "string", "description": "The affiliate's unique referral code.", "example": "a1b2c3d4" }, "referral_link": { "type": "string", "description": "The affiliate's shareable referral link. Traffic arriving through it is attributed to this affiliate.", "example": "https://creem.io/affiliate?code=a1b2c3d4" }, "clicks": { "type": "number", "description": "Total number of clicks recorded on the affiliate’s links.", "example": 128 }, "conversions": { "type": "number", "description": "Total number of conversions attributed to the affiliate.", "example": 12 }, "earnings": { "type": "number", "description": "Lifetime commission earned by the affiliate, in cents (1000 = $10.00), reported in a single primary currency (see `currency`). Affiliates earning in multiple currencies show only their highest-earning currency here; use the affiliate's commissions endpoint for the full per-currency breakdown.", "example": 4200 }, "currency": { "type": "string", "description": "Three-letter ISO currency code, in uppercase, for the `earnings` amount. This is the affiliate's primary (highest-earning) currency; commissions in other currencies are listed individually on the commissions endpoint.", "example": "USD" } }, "required": [ "id", "mode", "object", "email", "status", "referral_code", "referral_link", "clicks", "conversions", "earnings", "currency" ] }, "AffiliateListEntity": { "type": "object", "properties": { "items": { "description": "List of affiliate items", "items": { "$ref": "#/components/schemas/AffiliateEntity" }, "type": "array" }, "pagination": { "description": "Pagination details for the list", "allOf": [ { "$ref": "#/components/schemas/PaginationEntity" } ] } }, "required": [ "items", "pagination" ] }, "CommissionStatus": { "type": "string", "description": "The settlement status of the commission. `pending` while on hold, `approved` once cleared and available, `paid` once settled by a payout.", "enum": [ "pending", "approved", "paid" ] }, "CommissionEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object." }, "mode": { "$ref": "#/components/schemas/EnvironmentMode" }, "object": { "type": "string", "description": "String representing the object's type. Objects of the same type share the same value.", "example": "commission" }, "affiliate": { "type": "string", "description": "The ID of the affiliate this commission belongs to.", "example": "aff_1234567890" }, "amount": { "type": "number", "description": "The commission amount in cents. 1000 = $10.00", "example": 600 }, "currency": { "type": "string", "description": "Three-letter ISO currency code, in uppercase, for the commission amount.", "example": "USD" }, "status": { "example": "pending", "$ref": "#/components/schemas/CommissionStatus" }, "sale": { "type": "string", "description": "The ID of the sale transaction that generated this commission, if available.", "example": "tran_1234567890", "nullable": true }, "created_at": { "type": "number", "description": "Creation date of the commission as a timestamp." } }, "required": [ "id", "mode", "object", "affiliate", "amount", "currency", "status", "created_at" ] }, "CommissionListEntity": { "type": "object", "properties": { "items": { "description": "List of commission items", "items": { "$ref": "#/components/schemas/CommissionEntity" }, "type": "array" }, "pagination": { "description": "Pagination details for the list", "allOf": [ { "$ref": "#/components/schemas/PaginationEntity" } ] } }, "required": [ "items", "pagination" ] }, "CreateSplitRecipientRequestEntity": { "type": "object", "properties": { "recipient_type": { "type": "string", "description": "The kind of recipient: `store` for an existing store (add it directly), or `email` to invite someone by email (the split stays disabled until they accept).", "enum": [ "store", "email" ], "example": "store" }, "recipient_reference": { "type": "string", "description": "The recipient reference: a store id when `recipient_type` is `store`, or an email address when `recipient_type` is `email`.", "example": "store_1a2b3c4d" }, "amount": { "type": "number", "description": "The recipient's share as a percentage of the split net, from 1 to 100. The sum of all recipient shares must not exceed 100.", "example": 25, "minimum": 1, "maximum": 100 } }, "required": [ "recipient_type", "recipient_reference", "amount" ] }, "CreateSplitRequestEntity": { "type": "object", "properties": { "description": { "type": "string", "description": "An optional human-readable description of the split.", "example": "Q3 revenue share", "nullable": true }, "type": { "type": "string", "description": "What the split applies to: `store` (every payment to your store) or `product` (payments for one product).", "enum": [ "store", "product" ], "example": "store" }, "type_reference": { "type": "string", "description": "The id of the entity the split applies to: your store id when `type` is `store`, or the product id when `type` is `product`.", "example": "prod_1a2b3c4d" }, "recipients": { "description": "The recipients of the split and their percentage shares. Between 1 and 10 recipients; shares must sum to at most 100.", "type": "array", "items": { "$ref": "#/components/schemas/CreateSplitRecipientRequestEntity" } } }, "required": [ "type", "type_reference", "recipients" ] }, "SplitRecipientEntity": { "type": "object", "properties": { "type": { "type": "string", "description": "How the share is calculated. Currently always `percentage` — the recipient receives `amount` percent of the split net.", "enum": [ "fixed", "percentage" ], "example": "percentage" }, "recipient_type": { "type": "string", "description": "The kind of recipient. `store` and `user` are resolved (active) recipients; `email` is an invitee who has not yet accepted (the split share is held until they do).", "enum": [ "store", "user", "email" ], "example": "store" }, "recipient_reference": { "type": "string", "description": "Reference to the recipient: a store id (`recipient_type: store`), a user id (`recipient_type: user`), or a masked email address (`recipient_type: email`). Raw invitee email addresses are never returned.", "example": "store_1a2b3c4d" }, "amount": { "type": "number", "description": "The recipient share, as a percentage of the split net (e.g. 25 = 25%).", "example": 25 }, "enabled": { "type": "boolean", "description": "Whether this recipient is currently receiving its share. Email invitees start disabled until they accept.", "example": true }, "invite_status": { "type": "string", "description": "Invite lifecycle for email-type recipients that have not been accepted yet: `pending` (awaiting acceptance) or `declined`. Absent for resolved store/user recipients.", "enum": [ "pending", "declined" ], "example": "pending", "nullable": true } }, "required": [ "type", "recipient_type", "recipient_reference", "amount", "enabled" ] }, "SplitEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object." }, "mode": { "$ref": "#/components/schemas/EnvironmentMode" }, "object": { "type": "string", "description": "String representing the object's type. Objects of the same type share the same value.", "example": "split" }, "store_id": { "type": "string", "description": "The id of the store that owns this split.", "example": "store_1a2b3c4d" }, "description": { "type": "string", "description": "A human-readable description of the split.", "example": "Q3 revenue share", "nullable": true }, "type": { "type": "string", "description": "What the split applies to: `store` (every payment to the store) or `product` (payments for a specific product).", "enum": [ "store", "product" ], "example": "store" }, "type_reference": { "type": "string", "description": "The id of the entity the split applies to: the store id when `type` is `store`, or the product id when `type` is `product`.", "example": "prod_1a2b3c4d" }, "enabled": { "type": "boolean", "description": "Whether the split is active. A split created with email invitees starts disabled and activates once the first invitee accepts.", "example": true }, "recipients": { "description": "The recipients of the split and their shares.", "type": "array", "items": { "$ref": "#/components/schemas/SplitRecipientEntity" } }, "created_at": { "type": "number", "description": "Creation date of the split as a timestamp.", "example": 1735689600000 } }, "required": [ "id", "mode", "object", "store_id", "type", "type_reference", "enabled", "recipients", "created_at" ] }, "SplitListEntity": { "type": "object", "properties": { "items": { "description": "List of split items", "items": { "$ref": "#/components/schemas/SplitEntity" }, "type": "array" }, "pagination": { "description": "Pagination details for the list", "allOf": [ { "$ref": "#/components/schemas/PaginationEntity" } ] } }, "required": [ "items", "pagination" ] }, "WebhookSubscriptionEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object." }, "mode": { "$ref": "#/components/schemas/EnvironmentMode" }, "object": { "type": "string", "description": "String representing the object's type. Objects of the same type share the same value.", "example": "subscription" }, "product": { "description": "The product associated with the subscription.", "allOf": [ { "$ref": "#/components/schemas/ProductEntity" } ] }, "customer": { "description": "The customer who owns the subscription.", "allOf": [ { "$ref": "#/components/schemas/CustomerEntity" } ] }, "items": { "description": "Subscription items.", "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionItemEntity" } }, "collection_method": { "example": "charge_automatically", "$ref": "#/components/schemas/SubscriptionCollectionMethod" }, "status": { "example": "active", "$ref": "#/components/schemas/SubscriptionStatus" }, "last_transaction_id": { "type": "string", "description": "The ID of the last paid transaction.", "example": "tran_3e6Z6TzvHKdsjEgXnGDEp0" }, "last_transaction": { "description": "The last paid transaction.", "allOf": [ { "$ref": "#/components/schemas/TransactionEntity" } ] }, "last_transaction_date": { "format": "date-time", "type": "string", "description": "The date of the last paid transaction.", "example": "2024-09-12T12:34:56Z" }, "next_transaction_date": { "format": "date-time", "type": "string", "description": "The date when the next subscription transaction will be charged.", "example": "2024-09-12T12:34:56Z" }, "current_period_start_date": { "format": "date-time", "type": "string", "description": "The start date of the current subscription period.", "example": "2024-09-12T12:34:56Z" }, "current_period_end_date": { "format": "date-time", "type": "string", "description": "The end date of the current subscription period.", "example": "2024-09-12T12:34:56Z" }, "canceled_at": { "type": "string", "description": "The date and time when the subscription was canceled, if applicable.", "example": "2024-09-12T12:34:56Z", "format": "date-time", "nullable": true }, "created_at": { "format": "date-time", "type": "string", "description": "The date and time when the subscription was created.", "example": "2024-01-01T00:00:00Z" }, "updated_at": { "type": "string", "description": "The date and time when the subscription was last updated.", "example": "2024-09-12T12:34:56Z", "format": "date-time" }, "discount": { "type": "object", "description": "The discount applied to the subscription, if any.", "properties": { "id": { "type": "string", "description": "The unique identifier of the discount (e.g. dis_...).", "example": "dis_3e6Z6TzvHKdsjEgXnGDEp0" }, "discountCode": { "type": "string", "description": "The discount code applied to the subscription.", "example": "HOLIDAY2024" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "percentage", "fixed" ] }, "amount": { "type": "number" }, "duration": { "type": "string", "enum": [ "forever", "once", "repeating" ] }, "durationInMonths": { "type": "number" } } }, "metadata": { "type": "object", "description": "Metadata for the subscription in the form of key-value pairs.", "example": { "userId": "user_123", "plan": "pro" }, "additionalProperties": true } }, "required": [ "id", "mode", "object", "product", "customer", "collection_method", "status", "created_at", "updated_at" ], "x-speakeasy-include": true }, "WebhookCheckoutCompletedEventEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the event." }, "eventType": { "type": "string", "description": "The event name.", "enum": [ "checkout.completed" ] }, "created_at": { "type": "number", "description": "Creation date of the event." }, "object": { "description": "Object related to the event.", "allOf": [ { "$ref": "#/components/schemas/CheckoutEntity" } ] } }, "required": [ "id", "eventType", "created_at", "object" ], "x-speakeasy-include": true }, "RefundReason": { "type": "string", "description": "Reason for the refund.", "enum": [ "duplicate", "fraudulent", "requested_by_customer", "other" ] }, "RefundEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object." }, "mode": { "$ref": "#/components/schemas/EnvironmentMode" }, "object": { "type": "string", "description": "String representing the object’s type. Objects of the same type share the same value." }, "status": { "example": "succeeded", "$ref": "#/components/schemas/RefundStatus" }, "refund_amount": { "type": "number", "description": "The refunded amount in cents. 1000 = $10.00", "example": 1000 }, "refund_currency": { "type": "string", "description": "Three-letter ISO currency code, in uppercase. Must be a supported currency.", "example": "USD" }, "reason": { "$ref": "#/components/schemas/RefundReason" }, "transaction": { "description": "The transaction associated with the refund.", "allOf": [ { "$ref": "#/components/schemas/TransactionEntity" } ] }, "checkout": { "description": "The checkout associated with the refund.", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/CheckoutEntity" } ] }, "order": { "description": "The order associated with the refund.", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/OrderEntity" } ] }, "subscription": { "description": "The subscription associated with the refund.", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/SubscriptionEntity" } ] }, "customer": { "description": "The customer associated with the refund.", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/CustomerEntity" } ] }, "created_at": { "type": "number", "description": "Creation date of the order as timestamp" } }, "required": [ "id", "mode", "object", "status", "refund_amount", "refund_currency", "reason", "transaction", "created_at" ] }, "WebhookRefundCreatedEventEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the event." }, "eventType": { "type": "string", "description": "The event name.", "enum": [ "refund.created" ] }, "created_at": { "type": "number", "description": "Creation date of the event." }, "object": { "description": "Object related to the event.", "allOf": [ { "$ref": "#/components/schemas/RefundEntity" } ] } }, "required": [ "id", "eventType", "created_at", "object" ], "x-speakeasy-include": true }, "DisputeEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object." }, "mode": { "$ref": "#/components/schemas/EnvironmentMode" }, "object": { "type": "string", "description": "String representing the object's type. Objects of the same type share the same value." }, "amount": { "type": "number", "description": "The disputed amount in cents. 1000 = $10.00", "example": 1000 }, "currency": { "type": "string", "description": "Three-letter ISO currency code, in uppercase. Must be a supported currency.", "example": "USD" }, "transaction": { "description": "The transaction associated with the dispute.", "allOf": [ { "$ref": "#/components/schemas/TransactionEntity" } ] }, "checkout": { "description": "The checkout associated with the dispute.", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/CheckoutEntity" } ] }, "order": { "description": "The order associated with the dispute.", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/OrderEntity" } ] }, "subscription": { "description": "The subscription associated with the dispute.", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/SubscriptionEntity" } ] }, "customer": { "description": "The customer associated with the dispute.", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/CustomerEntity" } ] }, "created_at": { "type": "number", "description": "Creation date of the dispute as timestamp" } }, "required": [ "id", "mode", "object", "amount", "currency", "transaction", "created_at" ] }, "WebhookDisputeCreatedEventEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the event." }, "eventType": { "type": "string", "description": "The event name.", "enum": [ "dispute.created" ] }, "created_at": { "type": "number", "description": "Creation date of the event." }, "object": { "description": "Object related to the event.", "allOf": [ { "$ref": "#/components/schemas/DisputeEntity" } ] } }, "required": [ "id", "eventType", "created_at", "object" ], "x-speakeasy-include": true }, "CustomerCreditsExhaustionEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identity of this exhaustion episode. One episode spans from the first refused charge until credits are next added, so this value is the same across every signal about the same exhaustion." }, "object": { "type": "string", "description": "String representing the object type.", "enum": [ "customer_credits_exhaustion" ] }, "customer_id": { "type": "string", "description": "Identifier of the customer whose credits ran out." }, "bucket_name": { "type": "string", "description": "Name of the credit bucket that ran dry. Buckets are per customer, and a store may run several (for example one per meter)." }, "unit_label": { "type": "string", "description": "Display unit for the bucket, as configured on the meter (for example \"images\" or \"tokens\")." }, "shortfall_minor_units": { "type": "string", "description": "The charge that could not be covered, in minor units, serialised as a string to preserve precision." }, "occurred_at": { "type": "string", "description": "ISO-8601 instant at which the usage charge was refused for lack of credit." } }, "required": [ "id", "object", "customer_id", "bucket_name", "unit_label", "shortfall_minor_units", "occurred_at" ] }, "WebhookCustomerCreditsExhaustedEventEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the event." }, "eventType": { "type": "string", "description": "The event name.", "enum": [ "customer_credits.exhausted" ] }, "created_at": { "type": "number", "description": "Timestamp of when the event was created." }, "object": { "description": "Object related to the event.", "allOf": [ { "$ref": "#/components/schemas/CustomerCreditsExhaustionEntity" } ] } }, "required": [ "id", "eventType", "created_at", "object" ], "x-speakeasy-include": true }, "WebhookSubscriptionActiveEventEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the event." }, "eventType": { "type": "string", "description": "The event name.", "enum": [ "subscription.active" ] }, "created_at": { "type": "number", "description": "Creation date of the event." }, "object": { "description": "Object related to the event.", "allOf": [ { "$ref": "#/components/schemas/WebhookSubscriptionEntity" } ] } }, "required": [ "id", "eventType", "created_at", "object" ], "x-speakeasy-include": true }, "WebhookSubscriptionTrialingEventEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the event." }, "eventType": { "type": "string", "description": "The event name.", "enum": [ "subscription.trialing" ] }, "created_at": { "type": "number", "description": "Creation date of the event." }, "object": { "description": "Object related to the event.", "allOf": [ { "$ref": "#/components/schemas/WebhookSubscriptionEntity" } ] } }, "required": [ "id", "eventType", "created_at", "object" ], "x-speakeasy-include": true }, "WebhookSubscriptionCanceledEventEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the event." }, "eventType": { "type": "string", "description": "The event name.", "enum": [ "subscription.canceled" ] }, "created_at": { "type": "number", "description": "Creation date of the event." }, "object": { "description": "Object related to the event.", "allOf": [ { "$ref": "#/components/schemas/WebhookSubscriptionEntity" } ] } }, "required": [ "id", "eventType", "created_at", "object" ], "x-speakeasy-include": true }, "WebhookSubscriptionScheduledCancelEventEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the event." }, "eventType": { "type": "string", "description": "The event name.", "enum": [ "subscription.scheduled_cancel" ] }, "created_at": { "type": "number", "description": "Creation date of the event." }, "object": { "description": "Object related to the event.", "allOf": [ { "$ref": "#/components/schemas/WebhookSubscriptionEntity" } ] } }, "required": [ "id", "eventType", "created_at", "object" ], "x-speakeasy-include": true }, "WebhookSubscriptionPaidEventEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the event." }, "eventType": { "type": "string", "description": "The event name.", "enum": [ "subscription.paid" ] }, "created_at": { "type": "number", "description": "Creation date of the event." }, "object": { "description": "Object related to the event.", "allOf": [ { "$ref": "#/components/schemas/WebhookSubscriptionEntity" } ] } }, "required": [ "id", "eventType", "created_at", "object" ], "x-speakeasy-include": true }, "WebhookSubscriptionExpiredEventEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the event." }, "eventType": { "type": "string", "description": "The event name.", "enum": [ "subscription.expired" ] }, "created_at": { "type": "number", "description": "Creation date of the event." }, "object": { "description": "Object related to the event.", "allOf": [ { "$ref": "#/components/schemas/WebhookSubscriptionEntity" } ] } }, "required": [ "id", "eventType", "created_at", "object" ], "x-speakeasy-include": true }, "WebhookSubscriptionUnpaidEventEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the event." }, "eventType": { "type": "string", "description": "The event name.", "enum": [ "subscription.unpaid" ] }, "created_at": { "type": "number", "description": "Creation date of the event." }, "object": { "description": "Object related to the event.", "allOf": [ { "$ref": "#/components/schemas/WebhookSubscriptionEntity" } ] } }, "required": [ "id", "eventType", "created_at", "object" ], "x-speakeasy-include": true }, "WebhookSubscriptionUpdateEventEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the event." }, "eventType": { "type": "string", "description": "The event name.", "enum": [ "subscription.update" ] }, "created_at": { "type": "number", "description": "Creation date of the event." }, "object": { "description": "Object related to the event.", "allOf": [ { "$ref": "#/components/schemas/WebhookSubscriptionEntity" } ] } }, "required": [ "id", "eventType", "created_at", "object" ], "x-speakeasy-include": true }, "WebhookSubscriptionPastDueEventEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the event." }, "eventType": { "type": "string", "description": "The event name.", "enum": [ "subscription.past_due" ] }, "created_at": { "type": "number", "description": "Creation date of the event." }, "object": { "description": "Object related to the event.", "allOf": [ { "$ref": "#/components/schemas/WebhookSubscriptionEntity" } ] } }, "required": [ "id", "eventType", "created_at", "object" ], "x-speakeasy-include": true }, "WebhookSubscriptionPausedEventEntity": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the event." }, "eventType": { "type": "string", "description": "The event name.", "enum": [ "subscription.paused" ] }, "created_at": { "type": "number", "description": "Creation date of the event." }, "object": { "description": "Object related to the event.", "allOf": [ { "$ref": "#/components/schemas/WebhookSubscriptionEntity" } ] } }, "required": [ "id", "eventType", "created_at", "object" ], "x-speakeasy-include": true }, "WebhookEventEntity": { "description": "Webhook event delivered by Creem. The eventType property determines the shape of object.", "oneOf": [ { "$ref": "#/components/schemas/WebhookCheckoutCompletedEventEntity" }, { "$ref": "#/components/schemas/WebhookRefundCreatedEventEntity" }, { "$ref": "#/components/schemas/WebhookDisputeCreatedEventEntity" }, { "$ref": "#/components/schemas/WebhookCustomerCreditsExhaustedEventEntity" }, { "$ref": "#/components/schemas/WebhookSubscriptionActiveEventEntity" }, { "$ref": "#/components/schemas/WebhookSubscriptionTrialingEventEntity" }, { "$ref": "#/components/schemas/WebhookSubscriptionCanceledEventEntity" }, { "$ref": "#/components/schemas/WebhookSubscriptionScheduledCancelEventEntity" }, { "$ref": "#/components/schemas/WebhookSubscriptionPaidEventEntity" }, { "$ref": "#/components/schemas/WebhookSubscriptionExpiredEventEntity" }, { "$ref": "#/components/schemas/WebhookSubscriptionUnpaidEventEntity" }, { "$ref": "#/components/schemas/WebhookSubscriptionUpdateEventEntity" }, { "$ref": "#/components/schemas/WebhookSubscriptionPastDueEventEntity" }, { "$ref": "#/components/schemas/WebhookSubscriptionPausedEventEntity" } ], "discriminator": { "propertyName": "eventType", "mapping": { "checkout.completed": "#/components/schemas/WebhookCheckoutCompletedEventEntity", "refund.created": "#/components/schemas/WebhookRefundCreatedEventEntity", "dispute.created": "#/components/schemas/WebhookDisputeCreatedEventEntity", "customer_credits.exhausted": "#/components/schemas/WebhookCustomerCreditsExhaustedEventEntity", "subscription.active": "#/components/schemas/WebhookSubscriptionActiveEventEntity", "subscription.trialing": "#/components/schemas/WebhookSubscriptionTrialingEventEntity", "subscription.canceled": "#/components/schemas/WebhookSubscriptionCanceledEventEntity", "subscription.scheduled_cancel": "#/components/schemas/WebhookSubscriptionScheduledCancelEventEntity", "subscription.paid": "#/components/schemas/WebhookSubscriptionPaidEventEntity", "subscription.expired": "#/components/schemas/WebhookSubscriptionExpiredEventEntity", "subscription.unpaid": "#/components/schemas/WebhookSubscriptionUnpaidEventEntity", "subscription.update": "#/components/schemas/WebhookSubscriptionUpdateEventEntity", "subscription.past_due": "#/components/schemas/WebhookSubscriptionPastDueEventEntity", "subscription.paused": "#/components/schemas/WebhookSubscriptionPausedEventEntity" } }, "x-speakeasy-include": true } } }, "externalDocs": { "description": "Creem Documentation", "url": "https://docs.creem.io" } }