{ "openapi": "3.0.1", "info": { "title": "ChatDash API Documentation", "description": "API Documentation for the ChatDash Server", "version": "2.0.0" }, "servers": [ { "url": "https://api.chat-dash.com/v1/public" } ], "paths": { "/stripe/connect/accounts/{accountId}/products": { "get": { "tags": ["Stripe Connect"], "summary": "List Products", "description": "Retrieve a list of products for a connected account.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Stripe connected account ID", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter products by status: active, archived, or all. Defaults to active.", "schema": { "type": "string", "enum": ["active", "archived", "all"], "default": "active" } }, { "name": "limit", "in": "query", "required": false, "description": "Max number of products to return (1-100). Defaults to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "starting_after", "in": "query", "required": false, "description": "Pagination cursor (returns results after this ID).", "schema": { "type": "string" } }, { "name": "created_start", "in": "query", "required": false, "description": "Filter by created date start (unix timestamp, seconds).", "schema": { "type": "integer" } }, { "name": "created_end", "in": "query", "required": false, "description": "Filter by created date end (unix timestamp, seconds).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "example": "prod_ABC123XYZ" }, "productName": { "type": "string", "example": "Starter Plan" }, "description": { "type": "string", "nullable": true, "example": "Up to 100 minutes included" }, "taxBehavior": { "type": "string", "example": "exclusive" }, "pricing": { "type": "object", "properties": { "amount": { "type": "string", "example": "2999" }, "billingCycle": { "type": "string", "example": "month" }, "currency": { "type": "string", "example": "usd" }, "pricingModel": { "type": "string", "example": "base" }, "metrics": { "type": "string", "nullable": true, "example": "minutes" }, "usageLimit": { "type": "integer", "nullable": true, "example": 100 }, "overage": { "type": "string", "nullable": true, "description": "Overage price per unit in the smallest currency unit (e.g., cents for USD)", "example": "15" } } }, "creationDate": { "type": "integer", "example": 1700000000 }, "activeSubscriptionsCount": { "type": "integer", "example": 5 }, "status": { "type": "string", "example": "active" } } } }, "has_more": { "type": "boolean", "example": false }, "next_cursor": { "type": "string", "nullable": true, "example": null } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } }, "post": { "tags": ["Stripe Connect"], "summary": "Create Product", "description": "Create a product for a connected account.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Stripe connected account ID", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": ["pricing_model", "currency"], "properties": { "name": { "type": "string", "example": "Starter Plan" }, "description": { "type": "string", "example": "Up to 100 minutes included" }, "pricing_model": { "type": "string", "enum": ["base", "usage", "oneTime"], "description": "Required. Determines required pricing fields.", "example": "base" }, "currency": { "type": "string", "description": "Required. 3-letter ISO currency code.", "example": "usd" }, "period": { "type": "string", "enum": ["day", "week", "month", "year"], "description": "Required when pricing_model is not oneTime.", "example": "month" }, "metrics": { "type": "string", "enum": ["interactions", "minutes", "conversations", "valueBased"], "description": "Required when pricing_model is usage, or when pricing_model is base and usage_limit with overage_price is provided.", "example": "minutes" }, "base_price": { "type": "number", "description": "Required when pricing_model is base or oneTime. In smallest currency unit (e.g., cents for USD).", "example": 2999 }, "usage_price": { "type": "number", "description": "Required when pricing_model is usage. In smallest currency unit.", "example": 10 }, "usage_limit": { "type": "integer", "description": "If provided, overage_price is required.", "example": 100 }, "overage_price": { "type": "number", "description": "Required when usage_limit is provided. In smallest currency unit.", "example": 15 }, "tax_behavior": { "type": "string", "enum": ["inclusive", "exclusive", "unspecified"], "description": "Optional tax behavior.", "example": "exclusive" } } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "example": "prod_ABC123XYZ" }, "productName": { "type": "string", "example": "Starter Plan" }, "description": { "type": "string", "nullable": true, "example": "Up to 100 minutes included" }, "taxBehavior": { "type": "string", "example": "exclusive" }, "pricing": { "type": "object", "properties": { "amount": { "type": "string", "example": "2999" }, "billingCycle": { "type": "string", "example": "month" }, "currency": { "type": "string", "example": "usd" }, "pricingModel": { "type": "string", "example": "base" }, "metrics": { "type": "string", "nullable": true, "example": "minutes" }, "usageLimit": { "type": "integer", "nullable": true, "example": 100 }, "overage": { "type": "string", "nullable": true, "description": "Overage price per unit in the smallest currency unit (e.g., cents for USD)", "example": "15" } } }, "creationDate": { "type": "integer", "example": 1700000000 }, "activeSubscriptionsCount": { "type": "integer", "example": 0 }, "status": { "type": "string", "example": "active" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } } }, "/stripe/connect/accounts/{accountId}/products/{productId}": { "get": { "tags": ["Stripe Connect"], "summary": "Get Product", "description": "Retrieve a single product for a connected account.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Stripe connected account ID", "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "description": "The Stripe product ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "example": "prod_ABC123XYZ" }, "productName": { "type": "string", "example": "Starter Plan" }, "description": { "type": "string", "nullable": true, "example": "Up to 100 minutes included" }, "taxBehavior": { "type": "string", "example": "exclusive" }, "pricing": { "type": "object", "properties": { "amount": { "type": "string", "example": "2999" }, "billingCycle": { "type": "string", "example": "month" }, "currency": { "type": "string", "example": "usd" }, "pricingModel": { "type": "string", "example": "base" }, "metrics": { "type": "string", "nullable": true, "example": "minutes" }, "usageLimit": { "type": "integer", "nullable": true, "example": 100 }, "overage": { "type": "string", "nullable": true, "description": "Overage price per unit in the smallest currency unit (e.g., cents for USD)", "example": "15" } } }, "creationDate": { "type": "integer", "example": 1700000000 }, "activeSubscriptionsCount": { "type": "integer", "example": 5 }, "status": { "type": "string", "example": "active" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } }, "put": { "tags": ["Stripe Connect"], "summary": "Update Product", "description": "Update a product for a connected account.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Stripe connected account ID", "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "description": "The Stripe product ID", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "productId": { "type": "string", "example": "prod_ABC123XYZ" }, "productName": { "type": "string", "example": "Starter Plan Updated" }, "description": { "type": "string", "nullable": true, "example": "Updated description" }, "taxBehavior": { "type": "string", "example": "exclusive" }, "pricing": { "type": "object", "properties": { "amount": { "type": "string", "example": "2999" }, "billingCycle": { "type": "string", "example": "month" }, "currency": { "type": "string", "example": "usd" }, "pricingModel": { "type": "string", "example": "base" }, "metrics": { "type": "string", "nullable": true, "example": "minutes" }, "usageLimit": { "type": "integer", "nullable": true, "example": 100 }, "overage": { "type": "string", "nullable": true, "description": "Overage price per unit in the smallest currency unit (e.g., cents for USD)", "example": "15" } } }, "creationDate": { "type": "integer", "example": 1700000000 }, "activeSubscriptionsCount": { "type": "integer", "example": 5 }, "status": { "type": "string", "example": "active" } } } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } }, "delete": { "tags": ["Stripe Connect"], "summary": "Delete Product", "description": "Delete a product for a connected account.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Stripe connected account ID", "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "description": "The Stripe product ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The product ID that was deleted", "example": "prod_ABC123XYZ" }, "archived": { "type": "boolean", "description": "Indicates the product was successfully archived", "example": true } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } } }, "/stripe/connect/accounts/{accountId}/transactions": { "get": { "tags": ["Stripe Connect"], "summary": "List Transactions", "description": "Retrieve a list of transactions for a connected account.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Stripe connected account ID", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max number of transactions to return (1-100). Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "starting_after", "in": "query", "required": false, "description": "Pagination cursor (returns results after this ID).", "schema": { "type": "string" } }, { "name": "customer", "in": "query", "required": false, "description": "Filter by Stripe customer ID.", "schema": { "type": "string" } }, { "name": "created_start", "in": "query", "required": false, "description": "Filter by created date start (unix timestamp, seconds).", "schema": { "type": "integer" } }, { "name": "created_end", "in": "query", "required": false, "description": "Filter by created date end (unix timestamp, seconds).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The payment intent ID", "example": "pi_3ABC123DEF456GHI" }, "amount": { "type": "integer", "description": "Amount in smallest currency unit (e.g., cents for USD)", "example": 10000 }, "currency": { "type": "string", "description": "Three-letter ISO currency code", "example": "usd" }, "status": { "type": "string", "description": "Payment status", "example": "succeeded" }, "description": { "type": "string", "nullable": true, "description": "Description of the payment", "example": "Subscription creation" }, "customer": { "type": "object", "properties": { "id": { "type": "string", "example": "cus_ABC123XYZ" }, "email": { "type": "string", "example": "customer@example.com" }, "name": { "type": "string", "example": "John Doe" } } }, "created": { "type": "integer", "description": "Unix timestamp of when the transaction was created", "example": 1700000000 } } } }, "has_more": { "type": "boolean", "example": false }, "next_cursor": { "type": "string", "nullable": true, "example": null } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } } }, "/stripe/connect/accounts/{accountId}/transactions/{transactionId}": { "get": { "tags": ["Stripe Connect"], "summary": "Get Transaction", "description": "Retrieve a single transaction for a connected account.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Stripe connected account ID", "schema": { "type": "string" } }, { "name": "transactionId", "in": "path", "required": true, "description": "The Stripe transaction ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The payment intent ID", "example": "pi_3ABC123DEF456GHI" }, "amount": { "type": "integer", "description": "Amount in smallest currency unit (e.g., cents for USD)", "example": 10000 }, "currency": { "type": "string", "description": "Three-letter ISO currency code", "example": "usd" }, "status": { "type": "string", "description": "Payment status", "example": "succeeded" }, "description": { "type": "string", "nullable": true, "description": "Description of the payment", "example": "Subscription creation" }, "customer": { "type": "object", "properties": { "id": { "type": "string", "example": "cus_ABC123XYZ" }, "email": { "type": "string", "example": "customer@example.com" }, "name": { "type": "string", "example": "John Doe" } } }, "created": { "type": "integer", "description": "Unix timestamp of when the transaction was created", "example": 1700000000 } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } } }, "/stripe/connect/accounts/{accountId}/invoices": { "get": { "tags": ["Stripe Connect"], "summary": "List Invoices", "description": "Retrieve a list of invoices for a connected account.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Stripe connected account ID", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter invoices by status.", "schema": { "type": "string", "enum": ["draft", "open", "paid", "void", "uncollectible"] } }, { "name": "customer", "in": "query", "required": false, "description": "Filter by Stripe customer ID.", "schema": { "type": "string" } }, { "name": "created_start", "in": "query", "required": false, "description": "Filter by created date start (unix timestamp, seconds).", "schema": { "type": "integer" } }, { "name": "created_end", "in": "query", "required": false, "description": "Filter by created date end (unix timestamp, seconds).", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Max number of invoices to return (1-100). Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "starting_after", "in": "query", "required": false, "description": "Pagination cursor (returns results after this ID).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The invoice ID", "example": "in_1ABC123DEF456GHI" }, "amount": { "type": "integer", "description": "Amount in smallest currency unit (e.g., cents for USD)", "example": 10000 }, "currency": { "type": "string", "description": "Three-letter ISO currency code", "example": "usd" }, "status": { "type": "string", "description": "Invoice status", "enum": ["draft", "open", "paid", "void", "uncollectible"], "example": "paid" }, "number": { "type": "string", "nullable": true, "description": "Invoice number", "example": "GJXQAHMC-0001" }, "customer": { "type": "object", "properties": { "id": { "type": "string", "example": "cus_ABC123XYZ" }, "email": { "type": "string", "example": "customer@example.com" }, "name": { "type": "string", "example": "John Doe" } } }, "description": { "type": "string", "description": "Invoice description", "example": "" }, "created": { "type": "integer", "description": "Unix timestamp of when the invoice was created", "example": 1700000000 } } } }, "has_more": { "type": "boolean", "example": false }, "next_cursor": { "type": "string", "nullable": true, "example": null } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } }, "post": { "tags": ["Stripe Connect"], "summary": "Create Invoice", "description": "Create an invoice for a connected account.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Stripe connected account ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "properties": { "data": { "type": "object", "required": ["clientId", "productId", "collection_method"], "properties": { "clientId": { "type": "string", "description": "The client ID (must have an admin member assigned)", "example": "64abc123def456789012345a" }, "productId": { "type": "string", "description": "The Stripe product ID (must have a one-time price)", "example": "prod_ABC123XYZ" }, "collection_method": { "type": "string", "enum": ["charge_automatically", "send_invoice"], "description": "How to collect payment. If 'send_invoice', days_until_due is required.", "example": "send_invoice" }, "days_until_due": { "type": "integer", "description": "Number of days until the invoice is due. Required when collection_method is 'send_invoice'.", "example": 30 } } } } }, "example": { "data": { "clientId": "64abc123def456789012345a", "productId": "prod_ABC123XYZ", "collection_method": "send_invoice", "days_until_due": 30 } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The invoice ID", "example": "in_1ABC123DEF456GHI" }, "amount": { "type": "integer", "description": "Amount in smallest currency unit (e.g., cents for USD)", "example": 10000 }, "currency": { "type": "string", "description": "Three-letter ISO currency code", "example": "usd" }, "status": { "type": "string", "description": "Invoice status", "example": "draft" }, "number": { "type": "string", "nullable": true, "description": "Invoice number", "example": "GJXQAHMC-0001" }, "customer": { "type": "object", "properties": { "id": { "type": "string", "example": "cus_ABC123XYZ" }, "email": { "type": "string", "example": "customer@example.com" }, "name": { "type": "string", "example": "John Doe" } } }, "description": { "type": "string", "description": "Invoice description", "example": "" }, "created": { "type": "integer", "description": "Unix timestamp of when the invoice was created", "example": 1700000000 } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } } }, "/stripe/connect/accounts/{accountId}/invoices/{invoiceId}": { "get": { "tags": ["Stripe Connect"], "summary": "Get Invoice", "description": "Retrieve a single invoice for a connected account.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Stripe connected account ID", "schema": { "type": "string" } }, { "name": "invoiceId", "in": "path", "required": true, "description": "The Stripe invoice ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The invoice ID", "example": "in_1ABC123DEF456GHI" }, "amount": { "type": "integer", "description": "Amount in smallest currency unit (e.g., cents for USD)", "example": 10000 }, "currency": { "type": "string", "description": "Three-letter ISO currency code", "example": "usd" }, "status": { "type": "string", "description": "Invoice status", "enum": ["draft", "open", "paid", "void", "uncollectible"], "example": "paid" }, "number": { "type": "string", "nullable": true, "description": "Invoice number", "example": "GJXQAHMC-0001" }, "customer": { "type": "object", "properties": { "id": { "type": "string", "example": "cus_ABC123XYZ" }, "email": { "type": "string", "example": "customer@example.com" }, "name": { "type": "string", "example": "John Doe" } } }, "description": { "type": "string", "description": "Invoice description", "example": "" }, "created": { "type": "integer", "description": "Unix timestamp of when the invoice was created", "example": 1700000000 } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } } }, "/stripe/connect/accounts/{accountId}/subscriptions": { "get": { "tags": ["Stripe Connect"], "summary": "List Subscriptions", "description": "Retrieve a list of subscriptions for a connected account.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Stripe connected account ID", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter subscriptions by status. Defaults to active.", "schema": { "type": "string", "enum": [ "scheduled", "trialing", "active", "incomplete", "incomplete_expired", "past_due", "canceled", "unpaid", "paused" ], "default": "active" } }, { "name": "limit", "in": "query", "required": false, "description": "Max number of subscriptions to return (1-100). Defaults to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "starting_after", "in": "query", "required": false, "description": "Pagination cursor (returns results after this ID).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "sub_1ABC123DEF456GHI" }, "type": { "type": "string", "example": "subscription" }, "status": { "type": "string", "example": "active" }, "cancelAtPeriodEndDisplay": { "type": "string", "nullable": true, "example": null }, "customer": { "type": "object", "example": { "id": "cus_ABC123XYZ", "email": "customer@example.com" } }, "current_period_start": { "type": "integer", "nullable": true, "example": 1700000000 }, "current_period_end": { "type": "integer", "nullable": true, "example": 1702600000 }, "created": { "type": "integer", "example": 1700000000 }, "collection_method": { "type": "string", "example": "charge_automatically" }, "cancel_at_period_end": { "type": "boolean", "example": false }, "canceled_at": { "type": "integer", "nullable": true, "example": null }, "product": { "type": "object", "properties": { "id": { "type": "string", "example": "prod_ABC123XYZ" }, "name": { "type": "string", "example": "Pro Plan" } } }, "automatic_tax": { "type": "boolean", "example": false }, "coupon": { "type": "string", "example": "" }, "agents": { "type": "string", "example": "Agent 1, Agent 2" } } } }, "has_more": { "type": "boolean", "example": true }, "next_cursor": { "type": "string", "nullable": true, "example": "sub_2DEF456GHI789JKL" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } }, "post": { "tags": ["Stripe Connect"], "summary": "Create Subscription", "description": "Create a subscription for a connected account.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Stripe connected account ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "properties": { "data": { "type": "object", "required": ["clientId", "agentIds", "selectedProduct"], "properties": { "clientId": { "type": "string", "description": "The ID of the client (must have an admin member assigned)", "example": "64abc123def456789012345a" }, "agentIds": { "type": "array", "items": { "type": "string" }, "description": "Array of agent IDs to assign to this subscription", "example": ["64abc123def456789012345b", "64abc123def456789012345c"] }, "selectedProduct": { "type": "object", "required": ["productId", "startDate", "pricing"], "properties": { "productId": { "type": "string", "description": "The Stripe product ID to subscribe to", "example": "prod_ABC123XYZ" }, "startDate": { "type": "integer", "description": "Unix timestamp (seconds) for when the subscription should start", "example": 1700000000 }, "pricing": { "type": "object", "required": ["pricingModel"], "description": "Pricing configuration for the product", "properties": { "pricingModel": { "type": "string", "enum": ["base", "usage"], "description": "The pricing model type. Required. Note: 'oneTime' products cannot be used for subscriptions.", "example": "base" }, "metrics": { "type": "string", "enum": ["interactions", "minutes", "conversations", "valueBased"], "description": "The billing metric type for usage tracking. Required when pricingModel is 'usage' or when pricingModel is 'base' with usageLimit and overage.", "example": "minutes" }, "usageLimit": { "type": "number", "nullable": true, "description": "Usage limit for base pricing model. When provided with pricingModel 'base', overage and metrics are required.", "example": 1000 }, "overage": { "type": "number", "nullable": true, "description": "Overage price per unit after usage limit is reached. Required when usageLimit is provided.", "example": 0.05 } } }, "customAnalysisConfig": { "type": "object", "description": "Required when pricing.metrics is 'valueBased'", "properties": { "field": { "type": "string", "description": "The field to analyze for value-based billing", "example": "sentiment" }, "targetValue": { "type": "string", "description": "The target value to match", "example": "positive" } } } } }, "couponId": { "type": "string", "description": "Optional coupon ID to apply to the subscription", "example": "SUMMER20" }, "taxSettings": { "type": "object", "description": "Optional tax collection settings", "properties": { "enabled": { "type": "boolean", "description": "Whether to enable automatic tax collection", "example": true }, "country": { "type": "string", "description": "Two-letter ISO country code. Required when enabled is true", "example": "US" }, "postalCode": { "type": "string", "description": "Optional postal code for more accurate tax calculation", "example": "94102" } } } } } } }, "example": { "data": { "clientId": "64abc123def456789012345a", "agentIds": ["64abc123def456789012345b"], "selectedProduct": { "productId": "prod_ABC123XYZ", "startDate": 1700000000, "pricing": { "metrics": "minutes" } }, "couponId": "", "taxSettings": { "enabled": false } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The subscription schedule ID", "example": "sub_sched_1ABC123DEF456GHI" }, "type": { "type": "string", "example": "schedule" }, "status": { "type": "string", "example": "not_started" }, "customer": { "type": "object", "properties": { "id": { "type": "string", "example": "cus_ABC123XYZ" }, "email": { "type": "string", "example": "customer@example.com" } } }, "current_period_start": { "type": "integer", "nullable": true, "example": 1700000000 }, "current_period_end": { "type": "integer", "nullable": true, "example": 1702600000 }, "startDate": { "type": "integer", "nullable": true, "example": 1700000000 }, "created": { "type": "integer", "example": 1700000000 }, "collection_method": { "type": "string", "example": "charge_automatically" }, "cancel_at_period_end": { "type": "boolean", "example": false }, "canceled_at": { "type": "integer", "nullable": true, "example": null }, "product": { "type": "object", "properties": { "id": { "type": "string", "example": "prod_ABC123XYZ" }, "name": { "type": "string", "example": "Pro Plan" } } }, "automatic_tax": { "type": "boolean", "example": false }, "coupon": { "type": "string", "example": "" }, "priceIds": { "type": "array", "items": { "type": "string" }, "example": ["price_ABC123", "price_DEF456"] }, "agents": { "type": "string", "example": "Agent 1" }, "cancelAtPeriodEndDisplay": { "type": "string", "nullable": true, "example": null } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } } }, "/stripe/connect/accounts/{accountId}/subscriptions/by-customer": { "get": { "tags": ["Stripe Connect"], "summary": "List Subscriptions by Customer", "description": "Retrieve subscriptions for a connected account filtered by customer.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Stripe connected account ID", "schema": { "type": "string" } }, { "name": "customerId", "in": "query", "required": false, "description": "Filter by Stripe customer ID. Either customerId or email is required.", "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "description": "Filter by customer email. Either email or customerId is required.", "schema": { "type": "string", "format": "email" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "sub_1ABC123DEF456GHI" }, "type": { "type": "string", "example": "subscription" }, "status": { "type": "string", "example": "active" }, "cancelAtPeriodEndDisplay": { "type": "string", "nullable": true, "example": null }, "customer": { "type": "object", "example": { "id": "cus_ABC123XYZ", "email": "customer@example.com" } }, "current_period_start": { "type": "integer", "nullable": true, "example": 1700000000 }, "current_period_end": { "type": "integer", "nullable": true, "example": 1702600000 }, "created": { "type": "integer", "example": 1700000000 }, "collection_method": { "type": "string", "example": "charge_automatically" }, "cancel_at_period_end": { "type": "boolean", "example": false }, "canceled_at": { "type": "integer", "nullable": true, "example": null }, "product": { "type": "object", "properties": { "id": { "type": "string", "example": "prod_ABC123XYZ" }, "name": { "type": "string", "example": "Pro Plan" } } }, "automatic_tax": { "type": "boolean", "example": false }, "coupon": { "type": "string", "example": "" }, "agents": { "type": "string", "example": "Agent 1, Agent 2" } } } }, "has_more": { "type": "boolean", "example": false }, "next_cursor": { "type": "string", "nullable": true, "example": null } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } } }, "/stripe/connect/accounts/{accountId}/subscriptions/{subscriptionId}": { "get": { "tags": ["Stripe Connect"], "summary": "Get Subscription", "description": "Retrieve a single subscription for a connected account.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Stripe connected account ID", "schema": { "type": "string" } }, { "name": "subscriptionId", "in": "path", "required": true, "description": "The Stripe subscription ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "sub_1ABC123DEF456GHI" }, "type": { "type": "string", "example": "subscription" }, "status": { "type": "string", "example": "active" }, "cancelAtPeriodEndDisplay": { "type": "string", "nullable": true }, "customer": { "type": "string", "example": "cus_ABC123XYZ" }, "current_period_start": { "type": "integer", "example": 1700000000 }, "current_period_end": { "type": "integer", "example": 1702600000 }, "created": { "type": "integer", "example": 1700000000 }, "collection_method": { "type": "string", "example": "charge_automatically" }, "cancel_at_period_end": { "type": "boolean", "example": false }, "canceled_at": { "type": "integer", "nullable": true }, "product": { "type": "object", "properties": { "id": { "type": "string", "example": "prod_ABC123XYZ" }, "name": { "type": "string", "example": "Pro Plan" } } }, "automatic_tax": { "type": "boolean", "example": false }, "coupon": { "type": "string", "example": "" }, "agents": { "type": "string", "example": "Agent 1, Agent 2" }, "pricing": { "type": "object", "properties": { "amount": { "type": "string", "example": "2999" }, "billingCycle": { "type": "string", "example": "month" }, "currency": { "type": "string", "example": "usd" }, "pricingModel": { "type": "string", "example": "base" }, "metrics": { "type": "string", "example": "minutes" }, "usageLimit": { "type": "integer", "example": 100 }, "overage": { "type": "string", "description": "Overage price per unit in the smallest currency unit (e.g., cents for USD)", "example": "15" } } }, "totalPrice": { "type": "integer", "description": "Total price the client will be charged (base price plus usage charges) in the smallest currency unit", "example": 2999 }, "totalUsage": { "type": "number", "example": 45.5 } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } }, "put": { "tags": ["Stripe Connect"], "summary": "Update Subscription", "description": "Update a subscription for a connected account.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Stripe connected account ID", "schema": { "type": "string" } }, { "name": "subscriptionId", "in": "path", "required": true, "description": "The Stripe subscription ID", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "productId": { "type": "string", "description": "Required with startDate when updating a schedule (subscriptionId includes sched)." }, "startDate": { "type": "integer", "description": "Unix timestamp (seconds). Required with productId when updating a schedule." }, "taxSettings": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether to enable automatic tax collection", "example": true }, "country": { "type": "string", "description": "Two-letter ISO country code. Required when enabled is true.", "example": "US" }, "postalCode": { "type": "string", "description": "Postal code for tax calculation. Required for most countries when enabled is true.", "example": "94102" } } }, "cancelAtPeriodEnd": { "type": "boolean", "description": "Must be boolean. Not allowed for schedules; delete instead." } } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "sub_1ABC123DEF456GHI" }, "type": { "type": "string", "example": "subscription" }, "status": { "type": "string", "example": "active" }, "cancelAtPeriodEndDisplay": { "type": "string", "nullable": true, "example": null }, "customer": { "type": "object", "example": { "id": "cus_ABC123XYZ", "email": "customer@example.com" } }, "current_period_start": { "type": "integer", "nullable": true, "example": 1700000000 }, "current_period_end": { "type": "integer", "nullable": true, "example": 1702600000 }, "created": { "type": "integer", "example": 1700000000 }, "collection_method": { "type": "string", "example": "charge_automatically" }, "cancel_at_period_end": { "type": "boolean", "example": false }, "canceled_at": { "type": "integer", "nullable": true, "example": null }, "product": { "type": "object", "properties": { "id": { "type": "string", "example": "prod_ABC123XYZ" }, "name": { "type": "string", "example": "Pro Plan" } } }, "automatic_tax": { "type": "boolean", "example": false }, "coupon": { "type": "string", "example": "" }, "agents": { "type": "string", "example": "Agent 1, Agent 2" }, "priceIds": { "type": "array", "items": { "type": "string" }, "example": ["price_ABC123", "price_DEF456"] }, "startDate": { "type": "integer", "nullable": true, "example": 1700000000 } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } }, "delete": { "tags": ["Stripe Connect"], "summary": "Delete Subscription", "description": "Delete a subscription for a connected account.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Stripe connected account ID", "schema": { "type": "string" } }, { "name": "subscriptionId", "in": "path", "required": true, "description": "The Stripe subscription ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The subscription ID that was deleted", "example": "sub_1ABC123DEF456GHI" }, "canceled": { "type": "boolean", "description": "Indicates the subscription was successfully canceled", "example": true } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } } }, "/stripe/connect/accounts/{accountId}/coupons": { "get": { "tags": ["Stripe Connect"], "summary": "List Coupons", "description": "Retrieve a list of coupons for a connected account.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Stripe connected account ID", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max number of coupons to return (1-100). Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "starting_after", "in": "query", "required": false, "description": "Pagination cursor (returns results after this ID).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The coupon ID", "example": "SUMMER20" }, "object": { "type": "string", "example": "coupon" }, "amount_off": { "type": "integer", "nullable": true, "description": "Amount off in smallest currency unit", "example": null }, "created": { "type": "integer", "description": "Unix timestamp of when the coupon was created", "example": 1700000000 }, "currency": { "type": "string", "nullable": true, "example": "usd" }, "duration": { "type": "string", "enum": ["once", "repeating", "forever"], "example": "once" }, "duration_in_months": { "type": "integer", "nullable": true, "description": "Number of months the coupon applies (for repeating duration)", "example": null }, "livemode": { "type": "boolean", "example": true }, "max_redemptions": { "type": "integer", "nullable": true, "description": "Maximum number of times the coupon can be redeemed", "example": null }, "metadata": { "type": "object", "example": {} }, "name": { "type": "string", "description": "Display name of the coupon", "example": "Summer Sale" }, "percent_off": { "type": "number", "nullable": true, "description": "Percent discount (1-100)", "example": 25 }, "redeem_by": { "type": "integer", "nullable": true, "description": "Unix timestamp after which the coupon can no longer be redeemed", "example": null }, "times_redeemed": { "type": "integer", "description": "Number of times the coupon has been redeemed", "example": 0 }, "valid": { "type": "boolean", "description": "Whether the coupon is still valid", "example": true } } } }, "has_more": { "type": "boolean", "example": false }, "next_cursor": { "type": "string", "nullable": true, "example": null } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } }, "post": { "tags": ["Stripe Connect"], "summary": "Create Coupon", "description": "Create a coupon for a connected account.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Stripe connected account ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "properties": { "data": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name for the coupon", "example": "Summer Sale" }, "percent_off": { "type": "number", "description": "Percent discount (1-100). Required if amount_off is not provided.", "example": 25 }, "amount_off": { "type": "integer", "description": "Amount off in smallest currency unit. Required if percent_off is not provided.", "example": 1000 }, "currency": { "type": "string", "description": "Three-letter ISO currency code. Required when amount_off is provided.", "example": "usd" }, "duration": { "type": "string", "enum": ["once", "repeating", "forever"], "description": "How long the coupon applies. Defaults to 'once'.", "default": "once", "example": "once" }, "duration_in_months": { "type": "integer", "description": "Number of months the coupon applies. Required when duration is 'repeating'.", "example": 3 }, "max_redemptions": { "type": "integer", "description": "Maximum number of times the coupon can be redeemed", "example": 100 }, "redeem_by": { "type": "integer", "description": "Unix timestamp after which the coupon can no longer be redeemed", "example": 1735689600 } } } } }, "example": { "data": { "name": "Summer Sale", "percent_off": 25, "duration": "once" } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The coupon ID", "example": "SUMMER20" }, "object": { "type": "string", "example": "coupon" }, "amount_off": { "type": "integer", "nullable": true, "example": null }, "created": { "type": "integer", "example": 1700000000 }, "currency": { "type": "string", "nullable": true, "example": null }, "duration": { "type": "string", "example": "once" }, "duration_in_months": { "type": "integer", "nullable": true, "example": null }, "livemode": { "type": "boolean", "example": true }, "max_redemptions": { "type": "integer", "nullable": true, "example": null }, "metadata": { "type": "object", "example": {} }, "name": { "type": "string", "example": "Summer Sale" }, "percent_off": { "type": "number", "nullable": true, "example": 25 }, "redeem_by": { "type": "integer", "nullable": true, "example": null }, "times_redeemed": { "type": "integer", "example": 0 }, "valid": { "type": "boolean", "example": true } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } } }, "/stripe/connect/accounts/{accountId}/coupons/{couponId}": { "get": { "tags": ["Stripe Connect"], "summary": "Get Coupon", "description": "Retrieve a single coupon for a connected account.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Stripe connected account ID", "schema": { "type": "string" } }, { "name": "couponId", "in": "path", "required": true, "description": "The Stripe coupon ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The coupon ID", "example": "SUMMER20" }, "object": { "type": "string", "example": "coupon" }, "amount_off": { "type": "integer", "nullable": true, "example": null }, "created": { "type": "integer", "example": 1700000000 }, "currency": { "type": "string", "nullable": true, "example": null }, "duration": { "type": "string", "enum": ["once", "repeating", "forever"], "example": "once" }, "duration_in_months": { "type": "integer", "nullable": true, "example": null }, "livemode": { "type": "boolean", "example": true }, "max_redemptions": { "type": "integer", "nullable": true, "example": null }, "metadata": { "type": "object", "example": {} }, "name": { "type": "string", "example": "Summer Sale" }, "percent_off": { "type": "number", "nullable": true, "example": 25 }, "redeem_by": { "type": "integer", "nullable": true, "example": null }, "times_redeemed": { "type": "integer", "example": 0 }, "valid": { "type": "boolean", "example": true } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } }, "put": { "tags": ["Stripe Connect"], "summary": "Update Coupon", "description": "Update a coupon for a connected account.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Stripe connected account ID", "schema": { "type": "string" } }, { "name": "couponId", "in": "path", "required": true, "description": "The Stripe coupon ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "properties": { "data": { "type": "object", "properties": { "name": { "type": "string", "description": "The new display name for the coupon", "example": "Updated Coupon Name" } } } } }, "example": { "data": { "name": "Winter Sale" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "SUMMER20" }, "object": { "type": "string", "example": "coupon" }, "amount_off": { "type": "integer", "nullable": true, "example": null }, "created": { "type": "integer", "example": 1700000000 }, "currency": { "type": "string", "nullable": true, "example": null }, "duration": { "type": "string", "example": "once" }, "duration_in_months": { "type": "integer", "nullable": true, "example": null }, "livemode": { "type": "boolean", "example": true }, "max_redemptions": { "type": "integer", "nullable": true, "example": null }, "metadata": { "type": "object", "example": {} }, "name": { "type": "string", "example": "Winter Sale" }, "percent_off": { "type": "number", "nullable": true, "example": 25 }, "redeem_by": { "type": "integer", "nullable": true, "example": null }, "times_redeemed": { "type": "integer", "example": 0 }, "valid": { "type": "boolean", "example": true } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } }, "delete": { "tags": ["Stripe Connect"], "summary": "Delete Coupon", "description": "Delete a coupon for a connected account.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Stripe connected account ID", "schema": { "type": "string" } }, { "name": "couponId", "in": "path", "required": true, "description": "The Stripe coupon ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The coupon ID that was deleted", "example": "SUMMER20" }, "deleted": { "type": "boolean", "description": "Indicates the coupon was successfully deleted", "example": true } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } } }, "/stripe/connect/accounts/{accountId}/coupons/{couponId}/promotion-codes": { "get": { "tags": ["Stripe Connect"], "summary": "List Promotion Codes by Coupon", "description": "Retrieve promotion codes for a coupon on a connected account.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Stripe connected account ID", "schema": { "type": "string" } }, { "name": "couponId", "in": "path", "required": true, "description": "The Stripe coupon ID", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max number of promotion codes to return (1-100). Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "starting_after", "in": "query", "required": false, "description": "Pagination cursor (returns results after this ID).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the promotion code", "example": "promo_1SucFwRjNw7C4HMK01fsfjOh" }, "object": { "type": "string", "description": "Object type", "example": "promotion_code" }, "active": { "type": "boolean", "description": "Whether the promotion code is active", "example": true }, "code": { "type": "string", "description": "The customer-facing code", "example": "SUMMER20" }, "coupon": { "type": "object", "description": "The coupon associated with this promotion code", "properties": { "id": { "type": "string", "example": "rgJkxQB4" }, "object": { "type": "string", "example": "coupon" }, "amount_off": { "type": "integer", "nullable": true, "example": null }, "created": { "type": "integer", "description": "Unix timestamp of when coupon was created", "example": 1751915454 }, "currency": { "type": "string", "example": "usd" }, "duration": { "type": "string", "example": "repeating" }, "duration_in_months": { "type": "integer", "nullable": true, "example": 3 }, "livemode": { "type": "boolean", "example": true }, "max_redemptions": { "type": "integer", "nullable": true, "example": null }, "metadata": { "type": "object", "example": {} }, "name": { "type": "string", "example": "3Months Off" }, "percent_off": { "type": "number", "nullable": true, "example": 10 }, "redeem_by": { "type": "integer", "nullable": true, "example": null }, "times_redeemed": { "type": "integer", "example": 6 }, "valid": { "type": "boolean", "example": true } } }, "created": { "type": "integer", "description": "Unix timestamp of when the promotion code was created", "example": 1769620216 }, "customer": { "type": "string", "nullable": true, "description": "The customer that this promotion code can be used by, or null if it can be used by any customer", "example": "cus_TppcYxuTJKLNnG" }, "customer_account": { "type": "string", "nullable": true, "example": null }, "expires_at": { "type": "integer", "nullable": true, "description": "Unix timestamp of when the promotion code expires", "example": 1770137940 }, "livemode": { "type": "boolean", "example": true }, "max_redemptions": { "type": "integer", "nullable": true, "description": "Maximum number of times this promotion code can be redeemed", "example": 10 }, "metadata": { "type": "object", "example": {} }, "restrictions": { "type": "object", "properties": { "first_time_transaction": { "type": "boolean", "description": "Whether this promotion code is only valid for first time transactions", "example": true }, "minimum_amount": { "type": "integer", "nullable": true, "example": null }, "minimum_amount_currency": { "type": "string", "nullable": true, "example": null } } }, "times_redeemed": { "type": "integer", "description": "Number of times this promotion code has been redeemed", "example": 0 } } } }, "has_more": { "type": "boolean", "description": "Whether there are more results available", "example": false }, "next_cursor": { "type": "string", "nullable": true, "description": "Cursor for the next page of results", "example": null } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } } }, "/stripe/connect/accounts/{accountId}/promotion-codes": { "post": { "tags": ["Stripe Connect"], "summary": "Create Promotion Code", "description": "Create a promotion code for a connected account.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "All requests to the ChatDash API must be validated with the agency API Key found on your agency profile", "schema": { "type": "string" } }, { "name": "accountId", "in": "path", "required": true, "description": "The Stripe connected account ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "properties": { "data": { "type": "object", "required": ["coupon"], "properties": { "coupon": { "type": "string", "description": "The ID of the coupon to create a promotion code for (required)", "example": "rgJkxQB4" }, "code": { "type": "string", "description": "The customer-facing code. If not provided, Stripe will generate one", "example": "SUMMER20" }, "customer": { "type": "string", "description": "The customer ID that this promotion code can be used by. If not set, any customer can use it", "example": "cus_TppcYxuTJKLNnG" }, "max_redemptions": { "type": "integer", "description": "Maximum number of times this promotion code can be redeemed", "example": 10 }, "expires_at": { "type": "integer", "description": "Unix timestamp specifying when the promotion code expires", "example": 1770137940 }, "restrictions": { "type": "object", "description": "Restrictions on the promotion code", "properties": { "first_time_transaction": { "type": "boolean", "description": "Whether this promotion code is only valid for first time transactions", "example": true }, "minimum_amount": { "type": "integer", "description": "Minimum amount required to redeem this promotion code (in cents)", "example": 1000 }, "minimum_amount_currency": { "type": "string", "description": "Currency for minimum_amount", "example": "usd" } } } } } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the promotion code", "example": "promo_1SucFwRjNw7C4HMK01fsfjOh" }, "object": { "type": "string", "description": "Object type", "example": "promotion_code" }, "active": { "type": "boolean", "description": "Whether the promotion code is active", "example": true }, "code": { "type": "string", "description": "The customer-facing code", "example": "SUMMER20" }, "coupon": { "type": "object", "description": "The coupon associated with this promotion code", "properties": { "id": { "type": "string", "example": "rgJkxQB4" }, "object": { "type": "string", "example": "coupon" }, "amount_off": { "type": "integer", "nullable": true, "example": null }, "created": { "type": "integer", "example": 1751915454 }, "currency": { "type": "string", "example": "usd" }, "duration": { "type": "string", "example": "repeating" }, "duration_in_months": { "type": "integer", "nullable": true, "example": 3 }, "livemode": { "type": "boolean", "example": true }, "max_redemptions": { "type": "integer", "nullable": true, "example": null }, "metadata": { "type": "object", "example": {} }, "name": { "type": "string", "example": "3Months Off" }, "percent_off": { "type": "number", "nullable": true, "example": 10 }, "redeem_by": { "type": "integer", "nullable": true, "example": null }, "times_redeemed": { "type": "integer", "example": 6 }, "valid": { "type": "boolean", "example": true } } }, "created": { "type": "integer", "description": "Unix timestamp of when the promotion code was created", "example": 1769620216 }, "customer": { "type": "string", "nullable": true, "description": "The customer that this promotion code can be used by", "example": "cus_TppcYxuTJKLNnG" }, "customer_account": { "type": "string", "nullable": true, "example": null }, "expires_at": { "type": "integer", "nullable": true, "description": "Unix timestamp of when the promotion code expires", "example": 1770137940 }, "livemode": { "type": "boolean", "example": true }, "max_redemptions": { "type": "integer", "nullable": true, "example": 10 }, "metadata": { "type": "object", "example": {} }, "restrictions": { "type": "object", "properties": { "first_time_transaction": { "type": "boolean", "example": true }, "minimum_amount": { "type": "integer", "nullable": true, "example": null }, "minimum_amount_currency": { "type": "string", "nullable": true, "example": null } } }, "times_redeemed": { "type": "integer", "example": 0 } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Missing required field: coupon" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred" } } } } } } } } } }, "x-original-swagger-version": "2.0" }