{ "openapi": "3.1.0", "info": { "title": "Zaprite API", "description": "Build checkout and order flows on Zaprite with a single API for Orders, Contacts, and Webhooks.\n\n> The Zaprite API is designed for hosted checkout flows: create an order, send your customer to `checkoutUrl`, and use webhook events to keep your own product in sync.\n\nUsing TypeScript? Start with our [official JS SDK](https://www.npmjs.com/package/@zaprite/api) for typed request helpers and a faster integration.\n\n## Start Here\n\n1. Generate an API key in your [Zaprite API settings](https://app.zaprite.com/org/default/settings/api)\n2. Send it as a Bearer token in the `Authorization` header\n3. Create an order with pricing, customer, and redirect details\n4. Redirect your customer to the returned `checkoutUrl`\n5. Subscribe to webhook events so your system stays updated after payment\n\n## Base URL\n\nAll public API endpoints are served from:\n\n```text\nhttps://api.zaprite.com\n```\n\nResource paths are versioned under `/v1`, such as `/v1/orders` and `/v1/webhooks`.\n\n## Authentication\n\nAuthenticated endpoints expect a Bearer token in the `Authorization` header. Each API key is scoped to a single Zaprite organization, so requests automatically operate on that organization's data.\n\n```http\nAuthorization: Bearer YOUR_ZAPRITE_API_KEY\n```\n\nYou can create, rotate, and revoke keys in your [Zaprite API settings](https://app.zaprite.com/org/default/settings/api).\n\n## Errors\n\nZaprite uses standard HTTP status codes and returns a consistent error envelope:\n\n```json\n{\n \"code\": \"BAD_REQUEST\",\n \"message\": \"Invalid input data\",\n \"issues\": [\n {\n \"message\": \"Expected string, received number\"\n }\n ]\n}\n```\n\nThe `code` field is the machine-readable error code, the `message` field is the human-readable summary, and the optional `issues` array is most useful for validation failures where a request field is malformed or missing.\n\nIn practice, the most common API failures are:\n\n- `BAD_REQUEST` when request input is invalid\n- `UNAUTHORIZED` when the API key is missing, invalid, the organization is suspended, or the organization no longer has access to the action\n- `FORBIDDEN` when access to a resource is denied\n- `NOT_FOUND` when the resource does not exist for your organization\n- `INTERNAL_SERVER_ERROR` when Zaprite encounters an unexpected failure\n\nWhen handling errors, log the HTTP status code, `code`, and `message`. For `BAD_REQUEST` responses, inspect `issues` to display field-level feedback or to debug invalid request payloads quickly.\n\n## Pagination\n\nList endpoints return a consistent paginated envelope with up to 100 results per page. Use the `page` parameter to move through the collection and inspect the `meta` object to understand how many results remain.\n\n```json\n{\n \"items\": [],\n \"meta\": {\n \"itemsCount\": 42,\n \"pagesCount\": 1,\n \"page\": 1,\n \"perPage\": 100\n }\n}\n```\n\n## Metadata\n\nOrders support custom metadata so you can attach your own internal identifiers or workflow context to a payment flow. Metadata is returned on create, retrieve, and list responses for orders, which makes it a good place to store reconciliation fields from your own system.\n\n## Testing and Sandbox\n\nUse a sandbox organization to test your integration without moving real money. Sandbox organizations let you validate order creation, checkout redirects, and webhook flows before you point production traffic at Zaprite.\n\nIf you need a safe starting point, follow our [sandbox testing guide](https://help.zaprite.com/en/articles/9875022-how-to-test-payments-for-an-api-integration).\n\n## Webhooks\n\nWebhooks let Zaprite notify your system when order activity changes. A common production flow is: create an order, redirect the customer to checkout, then rely on webhook deliveries to confirm downstream fulfillment or status updates in your own system.\n\nIf your endpoint returns a non-`200` response, Zaprite retries the delivery multiple times before abandoning it. Make sure your webhook handler is fast, logs failures clearly, and can safely process the same business event more than once.\n\n## Developer Resources\n\n- **OpenAPI JSON** - [View the raw OpenAPI document](https://api.zaprite.com/openapi.json) for code generation and tooling\n- **LLM Docs** - [Read the Markdown version of these docs](https://api.zaprite.com/llms.txt) for AI workflows and plain-text reference\n- **Official JS SDK** - [@zaprite/api](https://www.npmjs.com/package/@zaprite/api) for Node.js and browser integrations\n- **Support** - Questions about the API? [Contact us](https://help.zaprite.com/)", "version": "1.0", "x-logo": { "url": "https://app.zaprite.com/zaprite.png", "altText": "Zaprite", "href": "https://zaprite.com" } }, "servers": [ { "url": "https://api.zaprite.com" } ], "tags": [ { "name": "Contacts", "description": "Create and manage customer contact records for use across your Zaprite workflows." }, { "name": "Orders", "description": "Create payment-ready orders, redirect customers to Zaprite Checkout, and retrieve or update order state." }, { "name": "Webhooks", "description": "Zaprite can send requests to your own server to notify you about events on your Zaprite organization. To receive those requests, add a webhook on your [Organization settings](https://app.zaprite.com/org/default/settings/api)." } ], "paths": { "/v1/orders": { "post": { "operationId": "order-create", "summary": "Create Order", "description": "Create a Zaprite Order. You can then send your customer to `checkoutUrl` to pay that Order. Note that Orders are not visible on your Zaprite dashboard until they have received a payment.
💡 To test your integration, you can create Zaprite sandbox Organizations that let you complete Orders with no real payment.

You can also create an invoice along with the order by providing the `invoice` field with line items. In this case, the order amount will be calculated from the invoice line items.", "tags": [ "Orders" ], "security": [ { "Authorization": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "description": "Amount denominated in currency smallest unit (e.g., cents for USD, satoshis for BTC). Example: `100` for $1.00 USD. Optional only if invoice is provided, in which case the amount will be calculated from invoice line items and amount will be ignored if provided.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "currency": { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, "externalUniqId": { "description": "Optionally, you can store your own unique ID for this order. This can be useful for reconciling payments with your own systems.", "type": "string" }, "redirectUrl": { "description": "Redirect your customer to this URL after they have paid for the order.", "type": "string", "format": "uri" }, "redirectIfPending": { "description": "If true, the customer will be redirected to `redirectUrl` even if the order is still pending (ie. Bitcoin transaction is unconfirmed).", "type": "boolean" }, "expiresAt": { "description": "ISO 8601 datetime when this order expires. After this time, the order cannot be paid unless a payment is already in progress.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "label": { "description": "Will be shown on the checkout page and in Bitcoin on-chain transaction labels.", "type": "string" }, "customCheckoutId": { "description": "If you want a custom checkout for specific orders, you can configure a new checkout at https://app.zaprite.com/org/default/settings/api", "type": "string" }, "contactId": { "description": "Optionally, you can associate the Order with one of your Zaprite contacts.", "type": "string" }, "sendReceiptToCustomer": { "description": "Whether to send a receipt email to the customer after successful payment. Defaults to true.", "default": true, "type": "boolean" }, "disablePaymentNotifs": { "description": "Whether to disable payment notifications to organization admins after successful payment. Defaults to false.", "type": "boolean" }, "customerData": { "type": "object", "properties": { "email": { "description": "If set, a payment receipt will be sent to this email upon payment.", "type": "string" }, "name": { "type": "string" } } }, "metadata": { "description": "Custom metadata for this order. Limited to 50 key-value pairs. Keys must be strings with a maximum length of 255 characters. Values must be strings with a maximum length of 1000 characters.", "type": "object", "propertyNames": { "type": "string", "maxLength": 255 }, "additionalProperties": { "type": "string", "maxLength": 1000 } }, "tags": { "description": "Add arbitrary tags to easily group and filter Orders in your reports. You can add up to 10 tags, each with a maximum length of 32 characters.", "type": "array", "items": { "type": "string", "maxLength": 32 } }, "invoice": { "description": "Optional invoice data. If provided, an invoice will be created for this order, and the order amount will be calculated from invoice line items. You must provide a `contactId` when creating an invoice.", "type": "object", "properties": { "title": { "description": "Optional title for the invoice", "type": "string", "maxLength": 255 }, "number": { "description": "Optional invoice number. If not provided, one will be generated", "type": "string", "maxLength": 255 }, "date": { "description": "Invoice date in YYYY-MM-DD format. Defaults to current date", "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, "daysToPay": { "description": "Number of days until payment is due. If not provided, the invoice will show \"DUE ON RECEIPT\"", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "purchaseOrderNumber": { "description": "Optional purchase order number", "type": "string", "maxLength": 255 }, "footerNote": { "description": "Optional note to display at the bottom of the invoice", "type": "string", "maxLength": 1000 }, "lineItems": { "description": "Line items for the invoice", "minItems": 1, "maxItems": 256, "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Name of the line item", "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "description": "Optional description of the line item", "type": "string", "maxLength": 1000 }, "quantity": { "description": "Quantity as a decimal number (e.g., 1.5 for one and a half units). Maximum of 2 decimal places allowed. Defaults to 1 if not provided.", "type": "number", "exclusiveMinimum": 0 }, "unitPrice": { "description": "Price per unit in currency smallest unit (e.g., cents for USD, satoshis for BTC). Can be negative for credits or adjustments.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "taxRateBips": { "description": "Tax rate in bips (e.g., 1000 = 10%)", "default": 0, "type": "integer", "minimum": 0, "maximum": 10000 }, "discountRateBips": { "description": "Discount rate in bips (e.g., 1000 = 10%)", "default": 0, "type": "integer", "minimum": 0, "maximum": 10000 }, "discountAmount": { "description": "Fixed discount amount in currency smallest unit (e.g., cents for USD, satoshis for BTC)", "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "name", "unitPrice" ] } } }, "required": [ "lineItems" ] }, "allowSavePaymentProfile": { "description": "If true and the selected payment method supports autopay, then the customer will be able to save their payment profile for future payments.", "type": "boolean" }, "customerFields": { "description": "Configure fields displayed on checkout page to collect customer information. Collected information will be stored in the `Order.customerData` field.", "type": "object", "properties": { "email": { "description": "Collect the customer email", "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "name": { "description": "Collect the customer name", "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "address": { "description": "Collect the customer full postal address", "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "phone": { "description": "Collect the customer phone number", "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "company": { "description": "Collect the customer company", "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "note": { "description": "Let the customer add a free-text note", "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] } } } }, "required": [ "currency" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "orgId": { "description": "Id of the Zaprite organization that created this order", "type": "string" }, "orderType": { "type": "string", "enum": [ "invoice", "paymentLink", "pos", "event", "wooCommerce", "paymentRequest", "other" ] }, "totalAmount": { "description": "Total amount to be paid by the customer in currency smallest unit (e.g. cents or sats)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, "externalUniqId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "description": "`PENDING`: The order is pending payment
`PROCESSING`: The order received a payment but the transaction is still pending (ie. an on-chain transaction with 0 conf or manual bank transfer awaiting manual confirmation)
`PAID`: The order was paid but it requires manual fulfillment to be flagged as `COMPLETE`
`COMPLETE`: The order was paid and is complete
`OVERPAID`: The order received a payment that was more than the total amount
`UNDERPAID`: The order received a payment that was less than the total amount", "type": "string", "enum": [ "PENDING", "PROCESSING", "PAID", "OVERPAID", "UNDERPAID", "COMPLETE" ] }, "paidAt": { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\"). `null` until the order is paid.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "description": "Date in ISO 8601 format when this order expires. After this time, the order cannot be paid.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "redirectUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "checkoutUrl": { "description": "Send your customer to this URL to complete the payment", "type": "string", "format": "uri" }, "receiptPdfUrl": { "description": "URL to download the Order receipt PDF. `null` until the order is paid.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "customCheckoutId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contact": { "anyOf": [ { "description": "Optional Zaprite contact associated with this order", "type": "object", "properties": { "id": { "type": "string" }, "legalName": { "type": "string" }, "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "taxId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultCurrency": { "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "billingAddress": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "line1", "line2", "zipCode", "city", "state", "countryCode" ], "additionalProperties": false }, { "type": "null" } ] }, "paymentProfiles": { "description": "Saved payment profiles for this contact. Can be used to pay Orders with the `charge` endpoint.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "method": { "type": "string" }, "label": { "type": "string" }, "expiresAt": { "anyOf": [ { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\")" }, { "type": "null" } ] }, "connection": { "type": "object", "properties": { "label": { "type": "string" }, "pluginSlug": { "type": "string" }, "id": { "type": "string" } }, "required": [ "label", "pluginSlug", "id" ], "additionalProperties": false }, "sourceOrder": { "description": "The Order that your customer was paying when saving this payment profile.", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "externalUniqId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "externalUniqId" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "externalId", "method", "label", "expiresAt", "connection", "sourceOrder" ], "additionalProperties": false } } }, "required": [ "id", "legalName", "contactName", "displayName", "email", "taxId", "defaultCurrency", "billingAddress", "paymentProfiles" ], "additionalProperties": false }, { "type": "null" } ] }, "invoice": { "description": "Set only if the order is for a Zaprite invoice (`orderType=\"invoice\"`), `null` otherwise", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "description": "Invoice number, displayed on the invoice page and PDF", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "orgId": { "type": "string" }, "status": { "type": "string", "enum": [ "DRAFT", "SENT", "PAID", "OVERPAID", "UNDERPAID" ] }, "footerNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "daysToPay": { "description": "Natural days from invoice date before the invoice is overdue. If null, invoice will be shown as \"DUE ON RECEIPT\"", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "date": { "description": "Date of the invoice, displayed on the invoice page and PDF. Format: YYYY-MM-DD", "type": "string" }, "purchaseOrderNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hideOrgAddress": { "description": "Organization address is hidden on the public invoice", "type": "boolean" }, "hideOrgEmail": { "description": "Organization email is hidden on the public invoice", "type": "boolean" }, "hideOrgName": { "description": "Organization name is hidden on the public invoice", "type": "boolean" }, "sentAt": { "description": "Date when the invoice was sent to the customer", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publicUrl": { "description": "URL to view the public invoice page", "type": "string", "format": "uri" }, "customer": { "anyOf": [ { "description": "**DEPRECATED:** Use `order.contact` instead", "type": "object", "properties": { "id": { "type": "string" }, "legalName": { "type": "string" }, "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "taxId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultCurrency": { "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "billingAddress": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "line1", "line2", "zipCode", "city", "state", "countryCode" ], "additionalProperties": false }, { "type": "null" } ] }, "paymentProfiles": { "description": "Saved payment profiles for this contact. Can be used to pay Orders with the `charge` endpoint.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "method": { "type": "string" }, "label": { "type": "string" }, "expiresAt": { "anyOf": [ { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\")" }, { "type": "null" } ] }, "connection": { "type": "object", "properties": { "label": { "type": "string" }, "pluginSlug": { "type": "string" }, "id": { "type": "string" } }, "required": [ "label", "pluginSlug", "id" ], "additionalProperties": false }, "sourceOrder": { "description": "The Order that your customer was paying when saving this payment profile.", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "externalUniqId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "externalUniqId" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "externalId", "method", "label", "expiresAt", "connection", "sourceOrder" ], "additionalProperties": false } } }, "required": [ "id", "legalName", "contactName", "displayName", "email", "taxId", "defaultCurrency", "billingAddress", "paymentProfiles" ], "additionalProperties": false }, { "type": "null" } ] }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unitPrice": { "description": "Price of the item in currency smallest unit (e.g. cents or sats)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "quantity": { "description": "Quantity of units (Max 2 decimal places)", "type": "number" }, "taxRateBips": { "description": "Tax rate in bips (e.g. 1234 for 12.34%)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "taxAmount": { "description": "In currency smallest unit (e.g. cents or sats)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "discountRateBips": { "description": "Discount rate in bips (e.g. 1234 for 12.34%)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "discountAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "name", "description", "unitPrice", "quantity", "taxRateBips", "taxAmount", "discountRateBips", "discountAmount" ], "additionalProperties": false } } }, "required": [ "id", "number", "title", "orgId", "status", "footerNote", "daysToPay", "date", "purchaseOrderNumber", "hideOrgAddress", "hideOrgEmail", "hideOrgName", "sentAt", "publicUrl", "customer", "lineItems" ], "additionalProperties": false }, { "type": "null" } ] }, "paymentLink": { "description": "Set only if the order was created from a Payment Link (`orderType=\"paymentLink\"`), `null` otherwise", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] }, "transactions": { "description": "All transactions this Order received", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\")" }, "amount": { "description": "Transaction amount in currency smallest unit (e.g. cents or sats)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, "amountInOrderCurrency": { "description": "Transaction amount denominated in the currency of the Order and in smallest unit (e.g. cents or sats)", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "discountsInOrderCurrency": { "description": "List premiums and discounts applied to this transaction. Note: The amount retained as payment for the Order is `amountInOrderCurrency + sum(discountsInChargeCurrency.amount)`", "type": "array", "items": { "type": "object", "properties": { "amountOff": { "description": "Amount of the discount denominated in `orderCurrency` and in smallest unit (e.g cents or sats). Negative value means a premium was applied.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rateBipsOff": { "description": "Rate of the discount in bips (e.g. 1234 for 12.34%). Negative value means a premium was applied.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "paymentType": { "description": "Type of payments this discount applies to", "type": "string", "enum": [ "FIAT", "BITCOIN", "LIGHTNING", "STABLECOIN" ] } }, "required": [ "amountOff", "rateBipsOff", "paymentType" ], "additionalProperties": false } }, "orderCurrency": { "description": "Currency of the Order this transaction is paying for. For example, when paying an USD invoice in BTC, transaction `currency` would be USD and `orderCurrency` USD.", "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "accountingCurrency": { "description": "The is the currency configured for your Organization", "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "amountInAccountingCurrency": { "description": "Transaction amount denominated in accounting currency and in smallest unit (e.g. cents or sats)", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "method": { "type": "string", "enum": [ "BITCOIN", "LIQUID", "LIGHTNING", "BANK", "CARD", "CASH", "CHECK", "GIFTCARD", "COUPON", "APPLEPAY", "GOOGLEPAY", "CASHAPP_PAY", "INTERAC", "ACH", "SEPA", "UNKNOWN", "WIRE_TRANSFER", "VENMO", "PAYPAL", "NO_CHARGE", "TETHER", "USDCIRCLE" ] }, "externalRef": { "description": "External reference for the transaction. (e.g. Bitcoin txId, Stripe transaction ID...)", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "CANCELED" ] } }, "required": [ "date", "amount", "currency", "amountInOrderCurrency", "discountsInOrderCurrency", "orderCurrency", "accountingCurrency", "amountInAccountingCurrency", "method", "externalRef", "status" ], "additionalProperties": false } }, "customerData": { "description": "Customer data collected on payment links if you enabled customer fields. Custom field values are included as additional keys.", "type": "object", "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "line1", "line2", "zipCode", "city", "state", "countryCode" ], "additionalProperties": false }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "email", "name", "phone", "address", "note", "company" ], "additionalProperties": {} }, "customerFields": { "description": "Configuration for fields displayed on checkout page to collect customer data", "type": "object", "properties": { "address": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "email": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "name": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "phone": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "note": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] } }, "additionalProperties": false }, "metadata": { "default": {}, "description": "Custom metadata for this order", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "tags": { "description": "Custom tags for this order", "type": "array", "items": { "type": "string" } }, "allowSavePaymentProfile": { "default": false, "description": "If true and the selected payment method supports autopay, then the customer will be able to save their payment profile for future payments.", "type": "boolean" }, "eventTickets": { "default": [], "description": "Event tickets issued for this order (empty if none).", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "paymentLinkItem": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "title" ], "additionalProperties": false } }, "required": [ "id", "paymentLinkItem" ], "additionalProperties": false } }, "orderItems": { "description": "Order items for this order. Empty if none.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "paymentLinkItem": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "label", "quantity", "paymentLinkItem" ], "additionalProperties": false } } }, "required": [ "id", "orgId", "orderType", "totalAmount", "currency", "externalUniqId", "status", "paidAt", "expiresAt", "redirectUrl", "label", "checkoutUrl", "receiptPdfUrl", "customCheckoutId", "contact", "invoice", "paymentLink", "transactions", "customerData", "customerFields", "metadata", "tags", "allowSavePaymentProfile", "eventTickets", "orderItems" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.BAD_REQUEST" } } } }, "401": { "description": "Authorization not provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.UNAUTHORIZED" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.FORBIDDEN" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.INTERNAL_SERVER_ERROR" } } } } } }, "get": { "operationId": "order-search", "summary": "List Orders", "description": "Retrieve a paginated list of orders with support for full-text search and filtering by date, status, currency, or contact. Returns up to 100 results per page. **Note:** To reduce noise, `PENDING` orders are excluded by default. To view them, explicitly set `includePending=true` or filter by a specific `status` (which overrides this default).", "tags": [ "Orders" ], "security": [ { "Authorization": [] } ], "parameters": [ { "in": "query", "name": "page", "schema": { "default": 1, "description": "Page number. 1 for first page", "type": "number", "minimum": 1 } }, { "in": "query", "name": "search", "schema": { "description": "Free text search. Searches in order id, externalUniqId, invoice number, customer info, contact info, order items labels, payment link title, and tags", "type": "string" }, "description": "Free text search. Searches in order id, externalUniqId, invoice number, customer info, contact info, order items labels, payment link title, and tags" }, { "in": "query", "name": "contactId", "schema": { "description": "Filter orders associated with a specific contact. Repeat the parameter to pass multiple values. Comma-separated is not supported.", "type": "array", "items": { "type": "string" } }, "description": "Filter orders associated with a specific contact. Repeat the parameter to pass multiple values. Comma-separated is not supported." }, { "in": "query", "name": "status", "schema": { "description": "Filter by order status. Accepts any Zaprite order status. Repeat the parameter to pass multiple values. Comma-separated is not supported.", "type": "array", "items": { "type": "string", "enum": [ "PENDING", "PROCESSING", "PAID", "OVERPAID", "UNDERPAID", "COMPLETE", "ABANDONED" ] } }, "description": "Filter by order status. Accepts any Zaprite order status. Repeat the parameter to pass multiple values. Comma-separated is not supported." }, { "in": "query", "name": "type", "schema": { "description": "Filter by order type: `invoice`, `paymentLink` (generic payment links), `pos`, `event`, `wooCommerce`, `paymentRequest`, or `other` (API-created orders).", "type": "string", "enum": [ "invoice", "paymentLink", "pos", "event", "wooCommerce", "paymentRequest", "other" ] }, "description": "Filter by order type: `invoice`, `paymentLink` (generic payment links), `pos`, `event`, `wooCommerce`, `paymentRequest`, or `other` (API-created orders)." }, { "in": "query", "name": "currency", "schema": { "description": "Filter by order currency (ISO 4217 or BTC/LBTC). Repeat the parameter to pass multiple values. Comma-separated is not supported.", "type": "array", "items": { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] } }, "description": "Filter by order currency (ISO 4217 or BTC/LBTC). Repeat the parameter to pass multiple values. Comma-separated is not supported." }, { "in": "query", "name": "createdAtMin", "schema": { "description": "Filter orders created after this date (ISO 8601 - e.g. \"2021-01-01T00:00:00.000Z\").", "format": "datetime string", "type": "string" }, "description": "Filter orders created after this date (ISO 8601 - e.g. \"2021-01-01T00:00:00.000Z\")." }, { "in": "query", "name": "createdAtMax", "schema": { "description": "Filter orders created before this date (ISO 8601 - e.g. \"2021-01-01T00:00:00.000Z\").", "format": "datetime string", "type": "string" }, "description": "Filter orders created before this date (ISO 8601 - e.g. \"2021-01-01T00:00:00.000Z\")." }, { "in": "query", "name": "paidAtMin", "schema": { "description": "Filter orders paid after this date (ISO 8601 - e.g. \"2021-01-01T00:00:00.000Z\"). Only matches paid Orders.", "format": "datetime string", "type": "string" }, "description": "Filter orders paid after this date (ISO 8601 - e.g. \"2021-01-01T00:00:00.000Z\"). Only matches paid Orders." }, { "in": "query", "name": "paidAtMax", "schema": { "description": "Filter orders paid before this date (ISO 8601 - e.g. \"2021-01-01T00:00:00.000Z\"). Only matches paid Orders.", "format": "datetime string", "type": "string" }, "description": "Filter orders paid before this date (ISO 8601 - e.g. \"2021-01-01T00:00:00.000Z\"). Only matches paid Orders." }, { "in": "query", "name": "tags", "schema": { "description": "Filter orders by tags. Returns orders that have any of the provided tags. Repeat the parameter to pass multiple values. Comma-separated is not supported.", "type": "array", "items": { "type": "string" } }, "description": "Filter orders by tags. Returns orders that have any of the provided tags. Repeat the parameter to pass multiple values. Comma-separated is not supported." }, { "in": "query", "name": "includePending", "schema": { "description": "If true, includes PENDING orders when no status filter is provided. Ignored if status filter is provided.", "default": "false", "type": "string", "enum": [ "true", "false" ] }, "description": "If true, includes PENDING orders when no status filter is provided. Ignored if status filter is provided." }, { "in": "query", "name": "sortBy", "schema": { "default": "createdAt", "type": "string", "enum": [ "createdAt", "paidAt" ] } }, { "in": "query", "name": "sortOrder", "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "orgId": { "description": "Id of the Zaprite organization that created this order", "type": "string" }, "orderType": { "type": "string", "enum": [ "invoice", "paymentLink", "pos", "event", "wooCommerce", "paymentRequest", "other" ] }, "totalAmount": { "description": "Total amount to be paid by the customer in currency smallest unit (e.g. cents or sats)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, "externalUniqId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "description": "`PENDING`: The order is pending payment
`PROCESSING`: The order received a payment but the transaction is still pending (ie. an on-chain transaction with 0 conf or manual bank transfer awaiting manual confirmation)
`PAID`: The order was paid but it requires manual fulfillment to be flagged as `COMPLETE`
`COMPLETE`: The order was paid and is complete
`OVERPAID`: The order received a payment that was more than the total amount
`UNDERPAID`: The order received a payment that was less than the total amount", "type": "string", "enum": [ "PENDING", "PROCESSING", "PAID", "OVERPAID", "UNDERPAID", "COMPLETE" ] }, "paidAt": { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\"). `null` until the order is paid.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "description": "Date in ISO 8601 format when this order expires. After this time, the order cannot be paid.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "redirectUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "checkoutUrl": { "description": "Send your customer to this URL to complete the payment", "type": "string", "format": "uri" }, "receiptPdfUrl": { "description": "URL to download the Order receipt PDF. `null` until the order is paid.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "customCheckoutId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contact": { "anyOf": [ { "description": "Optional Zaprite contact associated with this order", "type": "object", "properties": { "id": { "type": "string" }, "legalName": { "type": "string" }, "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "taxId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultCurrency": { "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "billingAddress": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "line1", "line2", "zipCode", "city", "state", "countryCode" ], "additionalProperties": false }, { "type": "null" } ] }, "paymentProfiles": { "description": "Saved payment profiles for this contact. Can be used to pay Orders with the `charge` endpoint.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "method": { "type": "string" }, "label": { "type": "string" }, "expiresAt": { "anyOf": [ { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\")" }, { "type": "null" } ] }, "connection": { "type": "object", "properties": { "label": { "type": "string" }, "pluginSlug": { "type": "string" }, "id": { "type": "string" } }, "required": [ "label", "pluginSlug", "id" ], "additionalProperties": false }, "sourceOrder": { "description": "The Order that your customer was paying when saving this payment profile.", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "externalUniqId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "externalUniqId" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "externalId", "method", "label", "expiresAt", "connection", "sourceOrder" ], "additionalProperties": false } } }, "required": [ "id", "legalName", "contactName", "displayName", "email", "taxId", "defaultCurrency", "billingAddress", "paymentProfiles" ], "additionalProperties": false }, { "type": "null" } ] }, "invoice": { "description": "Set only if the order is for a Zaprite invoice (`orderType=\"invoice\"`), `null` otherwise", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "description": "Invoice number, displayed on the invoice page and PDF", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "orgId": { "type": "string" }, "status": { "type": "string", "enum": [ "DRAFT", "SENT", "PAID", "OVERPAID", "UNDERPAID" ] }, "footerNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "daysToPay": { "description": "Natural days from invoice date before the invoice is overdue. If null, invoice will be shown as \"DUE ON RECEIPT\"", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "date": { "description": "Date of the invoice, displayed on the invoice page and PDF. Format: YYYY-MM-DD", "type": "string" }, "purchaseOrderNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hideOrgAddress": { "description": "Organization address is hidden on the public invoice", "type": "boolean" }, "hideOrgEmail": { "description": "Organization email is hidden on the public invoice", "type": "boolean" }, "hideOrgName": { "description": "Organization name is hidden on the public invoice", "type": "boolean" }, "sentAt": { "description": "Date when the invoice was sent to the customer", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publicUrl": { "description": "URL to view the public invoice page", "type": "string", "format": "uri" }, "customer": { "anyOf": [ { "description": "**DEPRECATED:** Use `order.contact` instead", "type": "object", "properties": { "id": { "type": "string" }, "legalName": { "type": "string" }, "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "taxId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultCurrency": { "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "billingAddress": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "line1", "line2", "zipCode", "city", "state", "countryCode" ], "additionalProperties": false }, { "type": "null" } ] }, "paymentProfiles": { "description": "Saved payment profiles for this contact. Can be used to pay Orders with the `charge` endpoint.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "method": { "type": "string" }, "label": { "type": "string" }, "expiresAt": { "anyOf": [ { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\")" }, { "type": "null" } ] }, "connection": { "type": "object", "properties": { "label": { "type": "string" }, "pluginSlug": { "type": "string" }, "id": { "type": "string" } }, "required": [ "label", "pluginSlug", "id" ], "additionalProperties": false }, "sourceOrder": { "description": "The Order that your customer was paying when saving this payment profile.", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "externalUniqId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "externalUniqId" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "externalId", "method", "label", "expiresAt", "connection", "sourceOrder" ], "additionalProperties": false } } }, "required": [ "id", "legalName", "contactName", "displayName", "email", "taxId", "defaultCurrency", "billingAddress", "paymentProfiles" ], "additionalProperties": false }, { "type": "null" } ] }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unitPrice": { "description": "Price of the item in currency smallest unit (e.g. cents or sats)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "quantity": { "description": "Quantity of units (Max 2 decimal places)", "type": "number" }, "taxRateBips": { "description": "Tax rate in bips (e.g. 1234 for 12.34%)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "taxAmount": { "description": "In currency smallest unit (e.g. cents or sats)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "discountRateBips": { "description": "Discount rate in bips (e.g. 1234 for 12.34%)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "discountAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "name", "description", "unitPrice", "quantity", "taxRateBips", "taxAmount", "discountRateBips", "discountAmount" ], "additionalProperties": false } } }, "required": [ "id", "number", "title", "orgId", "status", "footerNote", "daysToPay", "date", "purchaseOrderNumber", "hideOrgAddress", "hideOrgEmail", "hideOrgName", "sentAt", "publicUrl", "customer", "lineItems" ], "additionalProperties": false }, { "type": "null" } ] }, "paymentLink": { "description": "Set only if the order was created from a Payment Link (`orderType=\"paymentLink\"`), `null` otherwise", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] }, "transactions": { "description": "All transactions this Order received", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\")" }, "amount": { "description": "Transaction amount in currency smallest unit (e.g. cents or sats)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, "amountInOrderCurrency": { "description": "Transaction amount denominated in the currency of the Order and in smallest unit (e.g. cents or sats)", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "discountsInOrderCurrency": { "description": "List premiums and discounts applied to this transaction. Note: The amount retained as payment for the Order is `amountInOrderCurrency + sum(discountsInChargeCurrency.amount)`", "type": "array", "items": { "type": "object", "properties": { "amountOff": { "description": "Amount of the discount denominated in `orderCurrency` and in smallest unit (e.g cents or sats). Negative value means a premium was applied.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rateBipsOff": { "description": "Rate of the discount in bips (e.g. 1234 for 12.34%). Negative value means a premium was applied.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "paymentType": { "description": "Type of payments this discount applies to", "type": "string", "enum": [ "FIAT", "BITCOIN", "LIGHTNING", "STABLECOIN" ] } }, "required": [ "amountOff", "rateBipsOff", "paymentType" ], "additionalProperties": false } }, "orderCurrency": { "description": "Currency of the Order this transaction is paying for. For example, when paying an USD invoice in BTC, transaction `currency` would be USD and `orderCurrency` USD.", "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "accountingCurrency": { "description": "The is the currency configured for your Organization", "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "amountInAccountingCurrency": { "description": "Transaction amount denominated in accounting currency and in smallest unit (e.g. cents or sats)", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "method": { "type": "string", "enum": [ "BITCOIN", "LIQUID", "LIGHTNING", "BANK", "CARD", "CASH", "CHECK", "GIFTCARD", "COUPON", "APPLEPAY", "GOOGLEPAY", "CASHAPP_PAY", "INTERAC", "ACH", "SEPA", "UNKNOWN", "WIRE_TRANSFER", "VENMO", "PAYPAL", "NO_CHARGE", "TETHER", "USDCIRCLE" ] }, "externalRef": { "description": "External reference for the transaction. (e.g. Bitcoin txId, Stripe transaction ID...)", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "CANCELED" ] } }, "required": [ "date", "amount", "currency", "amountInOrderCurrency", "discountsInOrderCurrency", "orderCurrency", "accountingCurrency", "amountInAccountingCurrency", "method", "externalRef", "status" ], "additionalProperties": false } }, "customerData": { "description": "Customer data collected on payment links if you enabled customer fields. Custom field values are included as additional keys.", "type": "object", "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "line1", "line2", "zipCode", "city", "state", "countryCode" ], "additionalProperties": false }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "email", "name", "phone", "address", "note", "company" ], "additionalProperties": {} }, "customerFields": { "description": "Configuration for fields displayed on checkout page to collect customer data", "type": "object", "properties": { "address": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "email": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "name": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "phone": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "note": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] } }, "additionalProperties": false }, "metadata": { "default": {}, "description": "Custom metadata for this order", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "tags": { "description": "Custom tags for this order", "type": "array", "items": { "type": "string" } }, "allowSavePaymentProfile": { "default": false, "description": "If true and the selected payment method supports autopay, then the customer will be able to save their payment profile for future payments.", "type": "boolean" }, "eventTickets": { "default": [], "description": "Event tickets issued for this order (empty if none).", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "paymentLinkItem": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "title" ], "additionalProperties": false } }, "required": [ "id", "paymentLinkItem" ], "additionalProperties": false } }, "orderItems": { "description": "Order items for this order. Empty if none.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "paymentLinkItem": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "label", "quantity", "paymentLinkItem" ], "additionalProperties": false } } }, "required": [ "id", "orgId", "orderType", "totalAmount", "currency", "externalUniqId", "status", "paidAt", "expiresAt", "redirectUrl", "label", "checkoutUrl", "receiptPdfUrl", "customCheckoutId", "contact", "invoice", "paymentLink", "transactions", "customerData", "customerFields", "metadata", "tags", "allowSavePaymentProfile", "eventTickets", "orderItems" ], "additionalProperties": false } }, "meta": { "description": "Pagination metadata", "type": "object", "properties": { "itemsCount": { "type": "number" }, "pagesCount": { "type": "number" }, "page": { "type": "number" }, "perPage": { "type": "number" } }, "required": [ "itemsCount", "pagesCount", "page", "perPage" ], "additionalProperties": false } }, "required": [ "items", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.BAD_REQUEST" } } } }, "401": { "description": "Authorization not provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.UNAUTHORIZED" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.FORBIDDEN" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.NOT_FOUND" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.INTERNAL_SERVER_ERROR" } } } } } } }, "/v1/orders/{id}": { "patch": { "operationId": "order-update", "summary": "Edit Order", "description": "Update order status and expiration. Status updates are equivalent to using \"Mark as Complete\" in the Zaprite dashboard. When setting expiration to the past, new payments are prevented but in-flight payments will still be processed.", "tags": [ "Orders" ], "security": [ { "Authorization": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "description": "Zaprite `id` or `externalUniqId`", "type": "string" }, "required": true, "description": "Zaprite `id` or `externalUniqId`" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "New status for the order", "type": "string", "enum": [ "COMPLETE", "PAID" ] }, "expiresAt": { "description": "ISO 8601 datetime when this order expires. Set to anytime in past to immediately expire the order which prevents new payments (in-flight payments will still be processed). Set to null to remove expiration.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "orgId": { "description": "Id of the Zaprite organization that created this order", "type": "string" }, "orderType": { "type": "string", "enum": [ "invoice", "paymentLink", "pos", "event", "wooCommerce", "paymentRequest", "other" ] }, "totalAmount": { "description": "Total amount to be paid by the customer in currency smallest unit (e.g. cents or sats)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, "externalUniqId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "description": "`PENDING`: The order is pending payment
`PROCESSING`: The order received a payment but the transaction is still pending (ie. an on-chain transaction with 0 conf or manual bank transfer awaiting manual confirmation)
`PAID`: The order was paid but it requires manual fulfillment to be flagged as `COMPLETE`
`COMPLETE`: The order was paid and is complete
`OVERPAID`: The order received a payment that was more than the total amount
`UNDERPAID`: The order received a payment that was less than the total amount", "type": "string", "enum": [ "PENDING", "PROCESSING", "PAID", "OVERPAID", "UNDERPAID", "COMPLETE" ] }, "paidAt": { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\"). `null` until the order is paid.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "description": "Date in ISO 8601 format when this order expires. After this time, the order cannot be paid.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "redirectUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "checkoutUrl": { "description": "Send your customer to this URL to complete the payment", "type": "string", "format": "uri" }, "receiptPdfUrl": { "description": "URL to download the Order receipt PDF. `null` until the order is paid.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "customCheckoutId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contact": { "anyOf": [ { "description": "Optional Zaprite contact associated with this order", "type": "object", "properties": { "id": { "type": "string" }, "legalName": { "type": "string" }, "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "taxId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultCurrency": { "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "billingAddress": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "line1", "line2", "zipCode", "city", "state", "countryCode" ], "additionalProperties": false }, { "type": "null" } ] }, "paymentProfiles": { "description": "Saved payment profiles for this contact. Can be used to pay Orders with the `charge` endpoint.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "method": { "type": "string" }, "label": { "type": "string" }, "expiresAt": { "anyOf": [ { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\")" }, { "type": "null" } ] }, "connection": { "type": "object", "properties": { "label": { "type": "string" }, "pluginSlug": { "type": "string" }, "id": { "type": "string" } }, "required": [ "label", "pluginSlug", "id" ], "additionalProperties": false }, "sourceOrder": { "description": "The Order that your customer was paying when saving this payment profile.", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "externalUniqId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "externalUniqId" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "externalId", "method", "label", "expiresAt", "connection", "sourceOrder" ], "additionalProperties": false } } }, "required": [ "id", "legalName", "contactName", "displayName", "email", "taxId", "defaultCurrency", "billingAddress", "paymentProfiles" ], "additionalProperties": false }, { "type": "null" } ] }, "invoice": { "description": "Set only if the order is for a Zaprite invoice (`orderType=\"invoice\"`), `null` otherwise", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "description": "Invoice number, displayed on the invoice page and PDF", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "orgId": { "type": "string" }, "status": { "type": "string", "enum": [ "DRAFT", "SENT", "PAID", "OVERPAID", "UNDERPAID" ] }, "footerNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "daysToPay": { "description": "Natural days from invoice date before the invoice is overdue. If null, invoice will be shown as \"DUE ON RECEIPT\"", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "date": { "description": "Date of the invoice, displayed on the invoice page and PDF. Format: YYYY-MM-DD", "type": "string" }, "purchaseOrderNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hideOrgAddress": { "description": "Organization address is hidden on the public invoice", "type": "boolean" }, "hideOrgEmail": { "description": "Organization email is hidden on the public invoice", "type": "boolean" }, "hideOrgName": { "description": "Organization name is hidden on the public invoice", "type": "boolean" }, "sentAt": { "description": "Date when the invoice was sent to the customer", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publicUrl": { "description": "URL to view the public invoice page", "type": "string", "format": "uri" }, "customer": { "anyOf": [ { "description": "**DEPRECATED:** Use `order.contact` instead", "type": "object", "properties": { "id": { "type": "string" }, "legalName": { "type": "string" }, "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "taxId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultCurrency": { "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "billingAddress": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "line1", "line2", "zipCode", "city", "state", "countryCode" ], "additionalProperties": false }, { "type": "null" } ] }, "paymentProfiles": { "description": "Saved payment profiles for this contact. Can be used to pay Orders with the `charge` endpoint.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "method": { "type": "string" }, "label": { "type": "string" }, "expiresAt": { "anyOf": [ { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\")" }, { "type": "null" } ] }, "connection": { "type": "object", "properties": { "label": { "type": "string" }, "pluginSlug": { "type": "string" }, "id": { "type": "string" } }, "required": [ "label", "pluginSlug", "id" ], "additionalProperties": false }, "sourceOrder": { "description": "The Order that your customer was paying when saving this payment profile.", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "externalUniqId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "externalUniqId" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "externalId", "method", "label", "expiresAt", "connection", "sourceOrder" ], "additionalProperties": false } } }, "required": [ "id", "legalName", "contactName", "displayName", "email", "taxId", "defaultCurrency", "billingAddress", "paymentProfiles" ], "additionalProperties": false }, { "type": "null" } ] }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unitPrice": { "description": "Price of the item in currency smallest unit (e.g. cents or sats)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "quantity": { "description": "Quantity of units (Max 2 decimal places)", "type": "number" }, "taxRateBips": { "description": "Tax rate in bips (e.g. 1234 for 12.34%)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "taxAmount": { "description": "In currency smallest unit (e.g. cents or sats)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "discountRateBips": { "description": "Discount rate in bips (e.g. 1234 for 12.34%)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "discountAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "name", "description", "unitPrice", "quantity", "taxRateBips", "taxAmount", "discountRateBips", "discountAmount" ], "additionalProperties": false } } }, "required": [ "id", "number", "title", "orgId", "status", "footerNote", "daysToPay", "date", "purchaseOrderNumber", "hideOrgAddress", "hideOrgEmail", "hideOrgName", "sentAt", "publicUrl", "customer", "lineItems" ], "additionalProperties": false }, { "type": "null" } ] }, "paymentLink": { "description": "Set only if the order was created from a Payment Link (`orderType=\"paymentLink\"`), `null` otherwise", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] }, "transactions": { "description": "All transactions this Order received", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\")" }, "amount": { "description": "Transaction amount in currency smallest unit (e.g. cents or sats)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, "amountInOrderCurrency": { "description": "Transaction amount denominated in the currency of the Order and in smallest unit (e.g. cents or sats)", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "discountsInOrderCurrency": { "description": "List premiums and discounts applied to this transaction. Note: The amount retained as payment for the Order is `amountInOrderCurrency + sum(discountsInChargeCurrency.amount)`", "type": "array", "items": { "type": "object", "properties": { "amountOff": { "description": "Amount of the discount denominated in `orderCurrency` and in smallest unit (e.g cents or sats). Negative value means a premium was applied.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rateBipsOff": { "description": "Rate of the discount in bips (e.g. 1234 for 12.34%). Negative value means a premium was applied.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "paymentType": { "description": "Type of payments this discount applies to", "type": "string", "enum": [ "FIAT", "BITCOIN", "LIGHTNING", "STABLECOIN" ] } }, "required": [ "amountOff", "rateBipsOff", "paymentType" ], "additionalProperties": false } }, "orderCurrency": { "description": "Currency of the Order this transaction is paying for. For example, when paying an USD invoice in BTC, transaction `currency` would be USD and `orderCurrency` USD.", "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "accountingCurrency": { "description": "The is the currency configured for your Organization", "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "amountInAccountingCurrency": { "description": "Transaction amount denominated in accounting currency and in smallest unit (e.g. cents or sats)", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "method": { "type": "string", "enum": [ "BITCOIN", "LIQUID", "LIGHTNING", "BANK", "CARD", "CASH", "CHECK", "GIFTCARD", "COUPON", "APPLEPAY", "GOOGLEPAY", "CASHAPP_PAY", "INTERAC", "ACH", "SEPA", "UNKNOWN", "WIRE_TRANSFER", "VENMO", "PAYPAL", "NO_CHARGE", "TETHER", "USDCIRCLE" ] }, "externalRef": { "description": "External reference for the transaction. (e.g. Bitcoin txId, Stripe transaction ID...)", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "CANCELED" ] } }, "required": [ "date", "amount", "currency", "amountInOrderCurrency", "discountsInOrderCurrency", "orderCurrency", "accountingCurrency", "amountInAccountingCurrency", "method", "externalRef", "status" ], "additionalProperties": false } }, "customerData": { "description": "Customer data collected on payment links if you enabled customer fields. Custom field values are included as additional keys.", "type": "object", "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "line1", "line2", "zipCode", "city", "state", "countryCode" ], "additionalProperties": false }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "email", "name", "phone", "address", "note", "company" ], "additionalProperties": {} }, "customerFields": { "description": "Configuration for fields displayed on checkout page to collect customer data", "type": "object", "properties": { "address": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "email": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "name": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "phone": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "note": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] } }, "additionalProperties": false }, "metadata": { "default": {}, "description": "Custom metadata for this order", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "tags": { "description": "Custom tags for this order", "type": "array", "items": { "type": "string" } }, "allowSavePaymentProfile": { "default": false, "description": "If true and the selected payment method supports autopay, then the customer will be able to save their payment profile for future payments.", "type": "boolean" }, "eventTickets": { "default": [], "description": "Event tickets issued for this order (empty if none).", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "paymentLinkItem": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "title" ], "additionalProperties": false } }, "required": [ "id", "paymentLinkItem" ], "additionalProperties": false } }, "orderItems": { "description": "Order items for this order. Empty if none.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "paymentLinkItem": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "label", "quantity", "paymentLinkItem" ], "additionalProperties": false } } }, "required": [ "id", "orgId", "orderType", "totalAmount", "currency", "externalUniqId", "status", "paidAt", "expiresAt", "redirectUrl", "label", "checkoutUrl", "receiptPdfUrl", "customCheckoutId", "contact", "invoice", "paymentLink", "transactions", "customerData", "customerFields", "metadata", "tags", "allowSavePaymentProfile", "eventTickets", "orderItems" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.BAD_REQUEST" } } } }, "401": { "description": "Authorization not provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.UNAUTHORIZED" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.FORBIDDEN" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.NOT_FOUND" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.INTERNAL_SERVER_ERROR" } } } } } }, "get": { "operationId": "order-getById", "summary": "Get Order", "description": "Get an order by either it's Zaprite ID or your own ID (`externalUniqId`)", "tags": [ "Orders" ], "security": [ { "Authorization": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "description": "Zaprite `id` or `externalUniqId`", "type": "string" }, "required": true, "description": "Zaprite `id` or `externalUniqId`" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "orgId": { "description": "Id of the Zaprite organization that created this order", "type": "string" }, "orderType": { "type": "string", "enum": [ "invoice", "paymentLink", "pos", "event", "wooCommerce", "paymentRequest", "other" ] }, "totalAmount": { "description": "Total amount to be paid by the customer in currency smallest unit (e.g. cents or sats)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, "externalUniqId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "description": "`PENDING`: The order is pending payment
`PROCESSING`: The order received a payment but the transaction is still pending (ie. an on-chain transaction with 0 conf or manual bank transfer awaiting manual confirmation)
`PAID`: The order was paid but it requires manual fulfillment to be flagged as `COMPLETE`
`COMPLETE`: The order was paid and is complete
`OVERPAID`: The order received a payment that was more than the total amount
`UNDERPAID`: The order received a payment that was less than the total amount", "type": "string", "enum": [ "PENDING", "PROCESSING", "PAID", "OVERPAID", "UNDERPAID", "COMPLETE" ] }, "paidAt": { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\"). `null` until the order is paid.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "description": "Date in ISO 8601 format when this order expires. After this time, the order cannot be paid.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "redirectUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "checkoutUrl": { "description": "Send your customer to this URL to complete the payment", "type": "string", "format": "uri" }, "receiptPdfUrl": { "description": "URL to download the Order receipt PDF. `null` until the order is paid.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "customCheckoutId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contact": { "anyOf": [ { "description": "Optional Zaprite contact associated with this order", "type": "object", "properties": { "id": { "type": "string" }, "legalName": { "type": "string" }, "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "taxId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultCurrency": { "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "billingAddress": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "line1", "line2", "zipCode", "city", "state", "countryCode" ], "additionalProperties": false }, { "type": "null" } ] }, "paymentProfiles": { "description": "Saved payment profiles for this contact. Can be used to pay Orders with the `charge` endpoint.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "method": { "type": "string" }, "label": { "type": "string" }, "expiresAt": { "anyOf": [ { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\")" }, { "type": "null" } ] }, "connection": { "type": "object", "properties": { "label": { "type": "string" }, "pluginSlug": { "type": "string" }, "id": { "type": "string" } }, "required": [ "label", "pluginSlug", "id" ], "additionalProperties": false }, "sourceOrder": { "description": "The Order that your customer was paying when saving this payment profile.", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "externalUniqId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "externalUniqId" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "externalId", "method", "label", "expiresAt", "connection", "sourceOrder" ], "additionalProperties": false } } }, "required": [ "id", "legalName", "contactName", "displayName", "email", "taxId", "defaultCurrency", "billingAddress", "paymentProfiles" ], "additionalProperties": false }, { "type": "null" } ] }, "invoice": { "description": "Set only if the order is for a Zaprite invoice (`orderType=\"invoice\"`), `null` otherwise", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "description": "Invoice number, displayed on the invoice page and PDF", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "orgId": { "type": "string" }, "status": { "type": "string", "enum": [ "DRAFT", "SENT", "PAID", "OVERPAID", "UNDERPAID" ] }, "footerNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "daysToPay": { "description": "Natural days from invoice date before the invoice is overdue. If null, invoice will be shown as \"DUE ON RECEIPT\"", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "date": { "description": "Date of the invoice, displayed on the invoice page and PDF. Format: YYYY-MM-DD", "type": "string" }, "purchaseOrderNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hideOrgAddress": { "description": "Organization address is hidden on the public invoice", "type": "boolean" }, "hideOrgEmail": { "description": "Organization email is hidden on the public invoice", "type": "boolean" }, "hideOrgName": { "description": "Organization name is hidden on the public invoice", "type": "boolean" }, "sentAt": { "description": "Date when the invoice was sent to the customer", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publicUrl": { "description": "URL to view the public invoice page", "type": "string", "format": "uri" }, "customer": { "anyOf": [ { "description": "**DEPRECATED:** Use `order.contact` instead", "type": "object", "properties": { "id": { "type": "string" }, "legalName": { "type": "string" }, "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "taxId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultCurrency": { "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "billingAddress": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "line1", "line2", "zipCode", "city", "state", "countryCode" ], "additionalProperties": false }, { "type": "null" } ] }, "paymentProfiles": { "description": "Saved payment profiles for this contact. Can be used to pay Orders with the `charge` endpoint.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "method": { "type": "string" }, "label": { "type": "string" }, "expiresAt": { "anyOf": [ { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\")" }, { "type": "null" } ] }, "connection": { "type": "object", "properties": { "label": { "type": "string" }, "pluginSlug": { "type": "string" }, "id": { "type": "string" } }, "required": [ "label", "pluginSlug", "id" ], "additionalProperties": false }, "sourceOrder": { "description": "The Order that your customer was paying when saving this payment profile.", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "externalUniqId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "externalUniqId" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "externalId", "method", "label", "expiresAt", "connection", "sourceOrder" ], "additionalProperties": false } } }, "required": [ "id", "legalName", "contactName", "displayName", "email", "taxId", "defaultCurrency", "billingAddress", "paymentProfiles" ], "additionalProperties": false }, { "type": "null" } ] }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unitPrice": { "description": "Price of the item in currency smallest unit (e.g. cents or sats)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "quantity": { "description": "Quantity of units (Max 2 decimal places)", "type": "number" }, "taxRateBips": { "description": "Tax rate in bips (e.g. 1234 for 12.34%)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "taxAmount": { "description": "In currency smallest unit (e.g. cents or sats)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "discountRateBips": { "description": "Discount rate in bips (e.g. 1234 for 12.34%)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "discountAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "name", "description", "unitPrice", "quantity", "taxRateBips", "taxAmount", "discountRateBips", "discountAmount" ], "additionalProperties": false } } }, "required": [ "id", "number", "title", "orgId", "status", "footerNote", "daysToPay", "date", "purchaseOrderNumber", "hideOrgAddress", "hideOrgEmail", "hideOrgName", "sentAt", "publicUrl", "customer", "lineItems" ], "additionalProperties": false }, { "type": "null" } ] }, "paymentLink": { "description": "Set only if the order was created from a Payment Link (`orderType=\"paymentLink\"`), `null` otherwise", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] }, "transactions": { "description": "All transactions this Order received", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\")" }, "amount": { "description": "Transaction amount in currency smallest unit (e.g. cents or sats)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, "amountInOrderCurrency": { "description": "Transaction amount denominated in the currency of the Order and in smallest unit (e.g. cents or sats)", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "discountsInOrderCurrency": { "description": "List premiums and discounts applied to this transaction. Note: The amount retained as payment for the Order is `amountInOrderCurrency + sum(discountsInChargeCurrency.amount)`", "type": "array", "items": { "type": "object", "properties": { "amountOff": { "description": "Amount of the discount denominated in `orderCurrency` and in smallest unit (e.g cents or sats). Negative value means a premium was applied.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rateBipsOff": { "description": "Rate of the discount in bips (e.g. 1234 for 12.34%). Negative value means a premium was applied.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "paymentType": { "description": "Type of payments this discount applies to", "type": "string", "enum": [ "FIAT", "BITCOIN", "LIGHTNING", "STABLECOIN" ] } }, "required": [ "amountOff", "rateBipsOff", "paymentType" ], "additionalProperties": false } }, "orderCurrency": { "description": "Currency of the Order this transaction is paying for. For example, when paying an USD invoice in BTC, transaction `currency` would be USD and `orderCurrency` USD.", "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "accountingCurrency": { "description": "The is the currency configured for your Organization", "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "amountInAccountingCurrency": { "description": "Transaction amount denominated in accounting currency and in smallest unit (e.g. cents or sats)", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "method": { "type": "string", "enum": [ "BITCOIN", "LIQUID", "LIGHTNING", "BANK", "CARD", "CASH", "CHECK", "GIFTCARD", "COUPON", "APPLEPAY", "GOOGLEPAY", "CASHAPP_PAY", "INTERAC", "ACH", "SEPA", "UNKNOWN", "WIRE_TRANSFER", "VENMO", "PAYPAL", "NO_CHARGE", "TETHER", "USDCIRCLE" ] }, "externalRef": { "description": "External reference for the transaction. (e.g. Bitcoin txId, Stripe transaction ID...)", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "CANCELED" ] } }, "required": [ "date", "amount", "currency", "amountInOrderCurrency", "discountsInOrderCurrency", "orderCurrency", "accountingCurrency", "amountInAccountingCurrency", "method", "externalRef", "status" ], "additionalProperties": false } }, "customerData": { "description": "Customer data collected on payment links if you enabled customer fields. Custom field values are included as additional keys.", "type": "object", "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "line1", "line2", "zipCode", "city", "state", "countryCode" ], "additionalProperties": false }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "email", "name", "phone", "address", "note", "company" ], "additionalProperties": {} }, "customerFields": { "description": "Configuration for fields displayed on checkout page to collect customer data", "type": "object", "properties": { "address": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "email": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "name": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "phone": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "note": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] } }, "additionalProperties": false }, "metadata": { "default": {}, "description": "Custom metadata for this order", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "tags": { "description": "Custom tags for this order", "type": "array", "items": { "type": "string" } }, "allowSavePaymentProfile": { "default": false, "description": "If true and the selected payment method supports autopay, then the customer will be able to save their payment profile for future payments.", "type": "boolean" }, "eventTickets": { "default": [], "description": "Event tickets issued for this order (empty if none).", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "paymentLinkItem": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "title" ], "additionalProperties": false } }, "required": [ "id", "paymentLinkItem" ], "additionalProperties": false } }, "orderItems": { "description": "Order items for this order. Empty if none.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "paymentLinkItem": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "label", "quantity", "paymentLinkItem" ], "additionalProperties": false } } }, "required": [ "id", "orgId", "orderType", "totalAmount", "currency", "externalUniqId", "status", "paidAt", "expiresAt", "redirectUrl", "label", "checkoutUrl", "receiptPdfUrl", "customCheckoutId", "contact", "invoice", "paymentLink", "transactions", "customerData", "customerFields", "metadata", "tags", "allowSavePaymentProfile", "eventTickets", "orderItems" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.BAD_REQUEST" } } } }, "401": { "description": "Authorization not provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.UNAUTHORIZED" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.FORBIDDEN" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.NOT_FOUND" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.INTERNAL_SERVER_ERROR" } } } } } } }, "/v1/orders/charge": { "post": { "operationId": "order-charge", "summary": "Pay Order", "description": "Pay an Order with a payment profile previously saved by your customer.", "tags": [ "Orders" ], "security": [ { "Authorization": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "orderId": { "description": "Zaprite `id` or `externalUniqId`", "type": "string" }, "paymentProfileId": { "description": "You can find this id in `Contact.paymentProfiles`. Your Order checkout must enabled the connection for this payment profile.", "type": "string" }, "sendReceiptToCustomer": { "description": "Required field that must be explicitly set to true or false. If true, will send a receipt email to the customer after successful payment.", "type": "boolean" } }, "required": [ "orderId", "paymentProfileId", "sendReceiptToCustomer" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "orgId": { "description": "Id of the Zaprite organization that created this order", "type": "string" }, "orderType": { "type": "string", "enum": [ "invoice", "paymentLink", "pos", "event", "wooCommerce", "paymentRequest", "other" ] }, "totalAmount": { "description": "Total amount to be paid by the customer in currency smallest unit (e.g. cents or sats)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, "externalUniqId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "description": "`PENDING`: The order is pending payment
`PROCESSING`: The order received a payment but the transaction is still pending (ie. an on-chain transaction with 0 conf or manual bank transfer awaiting manual confirmation)
`PAID`: The order was paid but it requires manual fulfillment to be flagged as `COMPLETE`
`COMPLETE`: The order was paid and is complete
`OVERPAID`: The order received a payment that was more than the total amount
`UNDERPAID`: The order received a payment that was less than the total amount", "type": "string", "enum": [ "PENDING", "PROCESSING", "PAID", "OVERPAID", "UNDERPAID", "COMPLETE" ] }, "paidAt": { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\"). `null` until the order is paid.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "description": "Date in ISO 8601 format when this order expires. After this time, the order cannot be paid.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "redirectUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "checkoutUrl": { "description": "Send your customer to this URL to complete the payment", "type": "string", "format": "uri" }, "receiptPdfUrl": { "description": "URL to download the Order receipt PDF. `null` until the order is paid.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "customCheckoutId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contact": { "anyOf": [ { "description": "Optional Zaprite contact associated with this order", "type": "object", "properties": { "id": { "type": "string" }, "legalName": { "type": "string" }, "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "taxId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultCurrency": { "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "billingAddress": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "line1", "line2", "zipCode", "city", "state", "countryCode" ], "additionalProperties": false }, { "type": "null" } ] }, "paymentProfiles": { "description": "Saved payment profiles for this contact. Can be used to pay Orders with the `charge` endpoint.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "method": { "type": "string" }, "label": { "type": "string" }, "expiresAt": { "anyOf": [ { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\")" }, { "type": "null" } ] }, "connection": { "type": "object", "properties": { "label": { "type": "string" }, "pluginSlug": { "type": "string" }, "id": { "type": "string" } }, "required": [ "label", "pluginSlug", "id" ], "additionalProperties": false }, "sourceOrder": { "description": "The Order that your customer was paying when saving this payment profile.", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "externalUniqId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "externalUniqId" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "externalId", "method", "label", "expiresAt", "connection", "sourceOrder" ], "additionalProperties": false } } }, "required": [ "id", "legalName", "contactName", "displayName", "email", "taxId", "defaultCurrency", "billingAddress", "paymentProfiles" ], "additionalProperties": false }, { "type": "null" } ] }, "invoice": { "description": "Set only if the order is for a Zaprite invoice (`orderType=\"invoice\"`), `null` otherwise", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "description": "Invoice number, displayed on the invoice page and PDF", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "orgId": { "type": "string" }, "status": { "type": "string", "enum": [ "DRAFT", "SENT", "PAID", "OVERPAID", "UNDERPAID" ] }, "footerNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "daysToPay": { "description": "Natural days from invoice date before the invoice is overdue. If null, invoice will be shown as \"DUE ON RECEIPT\"", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "date": { "description": "Date of the invoice, displayed on the invoice page and PDF. Format: YYYY-MM-DD", "type": "string" }, "purchaseOrderNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hideOrgAddress": { "description": "Organization address is hidden on the public invoice", "type": "boolean" }, "hideOrgEmail": { "description": "Organization email is hidden on the public invoice", "type": "boolean" }, "hideOrgName": { "description": "Organization name is hidden on the public invoice", "type": "boolean" }, "sentAt": { "description": "Date when the invoice was sent to the customer", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publicUrl": { "description": "URL to view the public invoice page", "type": "string", "format": "uri" }, "customer": { "anyOf": [ { "description": "**DEPRECATED:** Use `order.contact` instead", "type": "object", "properties": { "id": { "type": "string" }, "legalName": { "type": "string" }, "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "taxId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultCurrency": { "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "billingAddress": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "line1", "line2", "zipCode", "city", "state", "countryCode" ], "additionalProperties": false }, { "type": "null" } ] }, "paymentProfiles": { "description": "Saved payment profiles for this contact. Can be used to pay Orders with the `charge` endpoint.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "method": { "type": "string" }, "label": { "type": "string" }, "expiresAt": { "anyOf": [ { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\")" }, { "type": "null" } ] }, "connection": { "type": "object", "properties": { "label": { "type": "string" }, "pluginSlug": { "type": "string" }, "id": { "type": "string" } }, "required": [ "label", "pluginSlug", "id" ], "additionalProperties": false }, "sourceOrder": { "description": "The Order that your customer was paying when saving this payment profile.", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "externalUniqId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "externalUniqId" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "externalId", "method", "label", "expiresAt", "connection", "sourceOrder" ], "additionalProperties": false } } }, "required": [ "id", "legalName", "contactName", "displayName", "email", "taxId", "defaultCurrency", "billingAddress", "paymentProfiles" ], "additionalProperties": false }, { "type": "null" } ] }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unitPrice": { "description": "Price of the item in currency smallest unit (e.g. cents or sats)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "quantity": { "description": "Quantity of units (Max 2 decimal places)", "type": "number" }, "taxRateBips": { "description": "Tax rate in bips (e.g. 1234 for 12.34%)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "taxAmount": { "description": "In currency smallest unit (e.g. cents or sats)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "discountRateBips": { "description": "Discount rate in bips (e.g. 1234 for 12.34%)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "discountAmount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "name", "description", "unitPrice", "quantity", "taxRateBips", "taxAmount", "discountRateBips", "discountAmount" ], "additionalProperties": false } } }, "required": [ "id", "number", "title", "orgId", "status", "footerNote", "daysToPay", "date", "purchaseOrderNumber", "hideOrgAddress", "hideOrgEmail", "hideOrgName", "sentAt", "publicUrl", "customer", "lineItems" ], "additionalProperties": false }, { "type": "null" } ] }, "paymentLink": { "description": "Set only if the order was created from a Payment Link (`orderType=\"paymentLink\"`), `null` otherwise", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] }, "transactions": { "description": "All transactions this Order received", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\")" }, "amount": { "description": "Transaction amount in currency smallest unit (e.g. cents or sats)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, "amountInOrderCurrency": { "description": "Transaction amount denominated in the currency of the Order and in smallest unit (e.g. cents or sats)", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "discountsInOrderCurrency": { "description": "List premiums and discounts applied to this transaction. Note: The amount retained as payment for the Order is `amountInOrderCurrency + sum(discountsInChargeCurrency.amount)`", "type": "array", "items": { "type": "object", "properties": { "amountOff": { "description": "Amount of the discount denominated in `orderCurrency` and in smallest unit (e.g cents or sats). Negative value means a premium was applied.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rateBipsOff": { "description": "Rate of the discount in bips (e.g. 1234 for 12.34%). Negative value means a premium was applied.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "paymentType": { "description": "Type of payments this discount applies to", "type": "string", "enum": [ "FIAT", "BITCOIN", "LIGHTNING", "STABLECOIN" ] } }, "required": [ "amountOff", "rateBipsOff", "paymentType" ], "additionalProperties": false } }, "orderCurrency": { "description": "Currency of the Order this transaction is paying for. For example, when paying an USD invoice in BTC, transaction `currency` would be USD and `orderCurrency` USD.", "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "accountingCurrency": { "description": "The is the currency configured for your Organization", "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "amountInAccountingCurrency": { "description": "Transaction amount denominated in accounting currency and in smallest unit (e.g. cents or sats)", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "method": { "type": "string", "enum": [ "BITCOIN", "LIQUID", "LIGHTNING", "BANK", "CARD", "CASH", "CHECK", "GIFTCARD", "COUPON", "APPLEPAY", "GOOGLEPAY", "CASHAPP_PAY", "INTERAC", "ACH", "SEPA", "UNKNOWN", "WIRE_TRANSFER", "VENMO", "PAYPAL", "NO_CHARGE", "TETHER", "USDCIRCLE" ] }, "externalRef": { "description": "External reference for the transaction. (e.g. Bitcoin txId, Stripe transaction ID...)", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "CANCELED" ] } }, "required": [ "date", "amount", "currency", "amountInOrderCurrency", "discountsInOrderCurrency", "orderCurrency", "accountingCurrency", "amountInAccountingCurrency", "method", "externalRef", "status" ], "additionalProperties": false } }, "customerData": { "description": "Customer data collected on payment links if you enabled customer fields. Custom field values are included as additional keys.", "type": "object", "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "line1", "line2", "zipCode", "city", "state", "countryCode" ], "additionalProperties": false }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "email", "name", "phone", "address", "note", "company" ], "additionalProperties": {} }, "customerFields": { "description": "Configuration for fields displayed on checkout page to collect customer data", "type": "object", "properties": { "address": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "email": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "name": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "phone": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] }, "note": { "type": "string", "enum": [ "REQUIRED", "OPTIONAL" ] } }, "additionalProperties": false }, "metadata": { "default": {}, "description": "Custom metadata for this order", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "tags": { "description": "Custom tags for this order", "type": "array", "items": { "type": "string" } }, "allowSavePaymentProfile": { "default": false, "description": "If true and the selected payment method supports autopay, then the customer will be able to save their payment profile for future payments.", "type": "boolean" }, "eventTickets": { "default": [], "description": "Event tickets issued for this order (empty if none).", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "paymentLinkItem": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "title" ], "additionalProperties": false } }, "required": [ "id", "paymentLinkItem" ], "additionalProperties": false } }, "orderItems": { "description": "Order items for this order. Empty if none.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "paymentLinkItem": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "label", "quantity", "paymentLinkItem" ], "additionalProperties": false } } }, "required": [ "id", "orgId", "orderType", "totalAmount", "currency", "externalUniqId", "status", "paidAt", "expiresAt", "redirectUrl", "label", "checkoutUrl", "receiptPdfUrl", "customCheckoutId", "contact", "invoice", "paymentLink", "transactions", "customerData", "customerFields", "metadata", "tags", "allowSavePaymentProfile", "eventTickets", "orderItems" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.BAD_REQUEST" } } } }, "401": { "description": "Authorization not provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.UNAUTHORIZED" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.FORBIDDEN" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.INTERNAL_SERVER_ERROR" } } } } } } }, "/v1/contacts": { "post": { "operationId": "contact-create", "summary": "Create Contact", "description": "Create a Zaprite Contact. You can then link this contact to Zaprite Orders.", "tags": [ "Contacts" ], "security": [ { "Authorization": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contactName": { "type": "string", "maxLength": 255 }, "displayName": { "type": "string", "maxLength": 255 }, "legalName": { "type": "string", "minLength": 1, "maxLength": 255 }, "email": { "type": "string", "maxLength": 255, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "internalNote": { "type": "string", "maxLength": 1000 }, "taxId": { "type": "string", "maxLength": 255 }, "defaultCurrency": { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, "billingAddress": { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string", "maxLength": 10 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "required": [ "legalName", "email" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "legalName": { "type": "string" }, "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "taxId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultCurrency": { "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "billingAddress": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "line1", "line2", "zipCode", "city", "state", "countryCode" ], "additionalProperties": false }, { "type": "null" } ] }, "paymentProfiles": { "description": "Saved payment profiles for this contact. Can be used to pay Orders with the `charge` endpoint.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "method": { "type": "string" }, "label": { "type": "string" }, "expiresAt": { "anyOf": [ { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\")" }, { "type": "null" } ] }, "connection": { "type": "object", "properties": { "label": { "type": "string" }, "pluginSlug": { "type": "string" }, "id": { "type": "string" } }, "required": [ "label", "pluginSlug", "id" ], "additionalProperties": false }, "sourceOrder": { "description": "The Order that your customer was paying when saving this payment profile.", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "externalUniqId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "externalUniqId" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "externalId", "method", "label", "expiresAt", "connection", "sourceOrder" ], "additionalProperties": false } } }, "required": [ "id", "legalName", "contactName", "displayName", "email", "taxId", "defaultCurrency", "billingAddress", "paymentProfiles" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.BAD_REQUEST" } } } }, "401": { "description": "Authorization not provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.UNAUTHORIZED" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.FORBIDDEN" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.INTERNAL_SERVER_ERROR" } } } } } }, "get": { "operationId": "contact-search", "summary": "List Contacts", "description": "List Zaprite Contacts. Returns up to 100 contacts per request.", "tags": [ "Contacts" ], "security": [ { "Authorization": [] } ], "parameters": [ { "in": "query", "name": "query", "schema": { "type": "string" } }, { "in": "query", "name": "email", "schema": { "type": "string" } }, { "in": "query", "name": "page", "schema": { "default": 1, "description": "Page number. 1 for first page", "type": "number", "minimum": 1 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "legalName": { "type": "string" }, "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "taxId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultCurrency": { "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "billingAddress": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "line1", "line2", "zipCode", "city", "state", "countryCode" ], "additionalProperties": false }, { "type": "null" } ] }, "paymentProfiles": { "description": "Saved payment profiles for this contact. Can be used to pay Orders with the `charge` endpoint.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "method": { "type": "string" }, "label": { "type": "string" }, "expiresAt": { "anyOf": [ { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\")" }, { "type": "null" } ] }, "connection": { "type": "object", "properties": { "label": { "type": "string" }, "pluginSlug": { "type": "string" }, "id": { "type": "string" } }, "required": [ "label", "pluginSlug", "id" ], "additionalProperties": false }, "sourceOrder": { "description": "The Order that your customer was paying when saving this payment profile.", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "externalUniqId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "externalUniqId" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "externalId", "method", "label", "expiresAt", "connection", "sourceOrder" ], "additionalProperties": false } } }, "required": [ "id", "legalName", "contactName", "displayName", "email", "taxId", "defaultCurrency", "billingAddress", "paymentProfiles" ], "additionalProperties": false } }, "meta": { "description": "Pagination metadata", "type": "object", "properties": { "itemsCount": { "type": "number" }, "pagesCount": { "type": "number" }, "page": { "type": "number" }, "perPage": { "type": "number" } }, "required": [ "itemsCount", "pagesCount", "page", "perPage" ], "additionalProperties": false } }, "required": [ "items", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.BAD_REQUEST" } } } }, "401": { "description": "Authorization not provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.UNAUTHORIZED" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.FORBIDDEN" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.NOT_FOUND" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.INTERNAL_SERVER_ERROR" } } } } } } }, "/v1/contacts/{id}": { "put": { "operationId": "contact-update", "summary": "Update Contact", "description": "Update a Zaprite Contact. Only provided fields are updated.", "tags": [ "Contacts" ], "security": [ { "Authorization": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contactName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "displayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "legalName": { "type": "string", "minLength": 1, "maxLength": 255 }, "email": { "anyOf": [ { "type": "string", "maxLength": 255, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "internalNote": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "taxId": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "defaultCurrency": { "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "billingAddress": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string", "maxLength": 10 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "legalName": { "type": "string" }, "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "taxId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultCurrency": { "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "billingAddress": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "line1", "line2", "zipCode", "city", "state", "countryCode" ], "additionalProperties": false }, { "type": "null" } ] }, "paymentProfiles": { "description": "Saved payment profiles for this contact. Can be used to pay Orders with the `charge` endpoint.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "method": { "type": "string" }, "label": { "type": "string" }, "expiresAt": { "anyOf": [ { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\")" }, { "type": "null" } ] }, "connection": { "type": "object", "properties": { "label": { "type": "string" }, "pluginSlug": { "type": "string" }, "id": { "type": "string" } }, "required": [ "label", "pluginSlug", "id" ], "additionalProperties": false }, "sourceOrder": { "description": "The Order that your customer was paying when saving this payment profile.", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "externalUniqId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "externalUniqId" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "externalId", "method", "label", "expiresAt", "connection", "sourceOrder" ], "additionalProperties": false } } }, "required": [ "id", "legalName", "contactName", "displayName", "email", "taxId", "defaultCurrency", "billingAddress", "paymentProfiles" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.BAD_REQUEST" } } } }, "401": { "description": "Authorization not provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.UNAUTHORIZED" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.FORBIDDEN" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.NOT_FOUND" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.INTERNAL_SERVER_ERROR" } } } } } }, "delete": { "operationId": "contact-delete", "summary": "Delete Contact", "description": "Delete a Zaprite Contact", "tags": [ "Contacts" ], "security": [ { "Authorization": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "400": { "description": "Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.BAD_REQUEST" } } } }, "401": { "description": "Authorization not provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.UNAUTHORIZED" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.FORBIDDEN" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.NOT_FOUND" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.INTERNAL_SERVER_ERROR" } } } } } }, "get": { "operationId": "contact-get", "summary": "Get Contact", "description": "Get a Zaprite Contact", "tags": [ "Contacts" ], "security": [ { "Authorization": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "legalName": { "type": "string" }, "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "taxId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultCurrency": { "anyOf": [ { "type": "string", "enum": [ "USD", "USDC", "USDT", "BTC", "LBTC", "ALL", "DZD", "ARS", "AMD", "AUD", "AZN", "BHD", "BDT", "BYN", "BMD", "BOB", "BAM", "BRL", "BGN", "KHR", "CAD", "CLP", "CNY", "COP", "CRC", "HRK", "CUP", "CZK", "DKK", "DOP", "EGP", "EUR", "GEL", "GHS", "GTQ", "HNL", "HKD", "HUF", "ISK", "INR", "IDR", "IRR", "IQD", "ILS", "JMD", "JPY", "JOD", "KZT", "KES", "KWD", "KGS", "LBP", "MKD", "MYR", "MUR", "MXN", "MDL", "MNT", "MAD", "MMK", "NAD", "NPR", "TWD", "NZD", "NIO", "NGN", "NOK", "OMR", "PKR", "PAB", "PEN", "PHP", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "KRW", "SSP", "VES", "LKR", "SEK", "CHF", "THB", "TTD", "TND", "TRY", "UGX", "UAH", "AED", "UYU", "UZS", "VND" ] }, { "type": "null" } ] }, "billingAddress": { "anyOf": [ { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zipCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "line1", "line2", "zipCode", "city", "state", "countryCode" ], "additionalProperties": false }, { "type": "null" } ] }, "paymentProfiles": { "description": "Saved payment profiles for this contact. Can be used to pay Orders with the `charge` endpoint.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "method": { "type": "string" }, "label": { "type": "string" }, "expiresAt": { "anyOf": [ { "description": "Date in ISO 8601 format (e.g. \"2021-01-01T00:00:00.000Z\")" }, { "type": "null" } ] }, "connection": { "type": "object", "properties": { "label": { "type": "string" }, "pluginSlug": { "type": "string" }, "id": { "type": "string" } }, "required": [ "label", "pluginSlug", "id" ], "additionalProperties": false }, "sourceOrder": { "description": "The Order that your customer was paying when saving this payment profile.", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "externalUniqId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "externalUniqId" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "externalId", "method", "label", "expiresAt", "connection", "sourceOrder" ], "additionalProperties": false } } }, "required": [ "id", "legalName", "contactName", "displayName", "email", "taxId", "defaultCurrency", "billingAddress", "paymentProfiles" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.BAD_REQUEST" } } } }, "401": { "description": "Authorization not provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.UNAUTHORIZED" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.FORBIDDEN" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.NOT_FOUND" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.INTERNAL_SERVER_ERROR" } } } } } } }, "/v1/webhooks": { "post": { "operationId": "webhook-create", "summary": "Create Webhook", "description": "Create a webhook to receive notifications about events in your Zaprite organization.", "tags": [ "Webhooks" ], "security": [ { "Authorization": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "description": "The URL that will receive webhook requests", "type": "string", "format": "uri" }, "label": { "description": "Optional label for the webhook", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "description": "The URL that will receive webhook requests", "type": "string", "format": "uri" }, "label": { "description": "Optional label for the webhook", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "description": "When the webhook was created" } }, "required": [ "id", "url", "label", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.BAD_REQUEST" } } } }, "401": { "description": "Authorization not provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.UNAUTHORIZED" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.FORBIDDEN" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.INTERNAL_SERVER_ERROR" } } } } } }, "get": { "operationId": "webhook-list", "summary": "List Webhooks", "description": "List all webhooks configured for your Zaprite organization. Returns up to 100 webhooks per request.", "tags": [ "Webhooks" ], "security": [ { "Authorization": [] } ], "parameters": [ { "in": "query", "name": "page", "schema": { "default": 1, "description": "Page number. 1 for first page", "type": "number", "minimum": 1 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "description": "The URL that will receive webhook requests", "type": "string", "format": "uri" }, "label": { "description": "Optional label for the webhook", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "description": "When the webhook was created" } }, "required": [ "id", "url", "label", "createdAt" ], "additionalProperties": false } }, "meta": { "description": "Pagination metadata", "type": "object", "properties": { "itemsCount": { "type": "number" }, "pagesCount": { "type": "number" }, "page": { "type": "number" }, "perPage": { "type": "number" } }, "required": [ "itemsCount", "pagesCount", "page", "perPage" ], "additionalProperties": false } }, "required": [ "items", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.BAD_REQUEST" } } } }, "401": { "description": "Authorization not provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.UNAUTHORIZED" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.FORBIDDEN" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.NOT_FOUND" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.INTERNAL_SERVER_ERROR" } } } } } } }, "/v1/webhooks/{id}": { "delete": { "operationId": "webhook-delete", "summary": "Delete Webhook", "description": "Delete a webhook from your Zaprite organization.", "tags": [ "Webhooks" ], "security": [ { "Authorization": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "400": { "description": "Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.BAD_REQUEST" } } } }, "401": { "description": "Authorization not provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.UNAUTHORIZED" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.FORBIDDEN" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.NOT_FOUND" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error.INTERNAL_SERVER_ERROR" } } } } } } } }, "components": { "schemas": { "error.BAD_REQUEST": { "title": "Invalid input data error (400)", "description": "The error information", "example": { "code": "BAD_REQUEST", "message": "Invalid input data", "issues": [] }, "type": "object", "properties": { "message": { "description": "The error message", "example": "Invalid input data", "type": "string" }, "code": { "description": "The error code", "example": "BAD_REQUEST", "type": "string" }, "issues": { "description": "An array of issues that were responsible for the error", "example": [], "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": false } } }, "required": [ "message", "code" ], "additionalProperties": false }, "error.UNAUTHORIZED": { "title": "Authorization not provided error (401)", "description": "The error information", "example": { "code": "UNAUTHORIZED", "message": "Authorization not provided", "issues": [] }, "type": "object", "properties": { "message": { "description": "The error message", "example": "Authorization not provided", "type": "string" }, "code": { "description": "The error code", "example": "UNAUTHORIZED", "type": "string" }, "issues": { "description": "An array of issues that were responsible for the error", "example": [], "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": false } } }, "required": [ "message", "code" ], "additionalProperties": false }, "error.FORBIDDEN": { "title": "Insufficient access error (403)", "description": "The error information", "example": { "code": "FORBIDDEN", "message": "Insufficient access", "issues": [] }, "type": "object", "properties": { "message": { "description": "The error message", "example": "Insufficient access", "type": "string" }, "code": { "description": "The error code", "example": "FORBIDDEN", "type": "string" }, "issues": { "description": "An array of issues that were responsible for the error", "example": [], "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": false } } }, "required": [ "message", "code" ], "additionalProperties": false }, "error.INTERNAL_SERVER_ERROR": { "title": "Internal server error error (500)", "description": "The error information", "example": { "code": "INTERNAL_SERVER_ERROR", "message": "Internal server error", "issues": [] }, "type": "object", "properties": { "message": { "description": "The error message", "example": "Internal server error", "type": "string" }, "code": { "description": "The error code", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "issues": { "description": "An array of issues that were responsible for the error", "example": [], "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": false } } }, "required": [ "message", "code" ], "additionalProperties": false }, "error.NOT_FOUND": { "title": "Not found error (404)", "description": "The error information", "example": { "code": "NOT_FOUND", "message": "Not found", "issues": [] }, "type": "object", "properties": { "message": { "description": "The error message", "example": "Not found", "type": "string" }, "code": { "description": "The error code", "example": "NOT_FOUND", "type": "string" }, "issues": { "description": "An array of issues that were responsible for the error", "example": [], "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": false } } }, "required": [ "message", "code" ], "additionalProperties": false } }, "securitySchemes": { "Authorization": { "type": "http", "scheme": "bearer", "description": "Enter your Zaprite API key. You can find and manage your keys in your [Zaprite API settings](https://app.zaprite.com/org/default/settings/api)." } } }, "webhooks": { "order.change": { "post": { "tags": [ "Webhooks" ], "summary": "order.change", "description": "Sent to your own server when an Order status changes. You can use this hook to detect paid orders.", "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "eventType": { "type": "string", "const": "order.change" }, "orderId": { "description": "You can get order details by fetching the Order", "type": "string" }, "orgId": { "description": "ID of the Zaprite Organization", "type": "string" } }, "required": [ "eventType", "orderId", "orgId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Return a **200** status to indicate that the data was received successfully. If your server returns an error HTTP code, we will retry sending multiple times then abandon the message if all attempts failed." } } } }, "invoice.sent": { "post": { "tags": [ "Webhooks" ], "summary": "invoice.sent", "description": "Sent to your own server when an invoice is sent.", "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "eventType": { "type": "string", "const": "invoice.sent" }, "orderId": { "description": "You can get invoice details by fetching the related Order", "type": "string" }, "orgId": { "description": "ID of the Zaprite Organization", "type": "string" } }, "required": [ "eventType", "orderId", "orgId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Return a **200** status to indicate that the data was received successfully. If your server returns an error HTTP code, we will retry sending multiple times then abandon the message if all attempts failed." } } } }, "contact.updated": { "post": { "tags": [ "Webhooks" ], "summary": "contact.updated", "description": "Sent to your own server when a Contact is updated.", "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "eventType": { "type": "string", "const": "contact.updated" }, "contactId": { "description": "You can get Contact details by fetching the Contact", "type": "string" }, "orgId": { "description": "ID of the Zaprite Organization", "type": "string" } }, "required": [ "eventType", "contactId", "orgId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Return a **200** status to indicate that the data was received successfully. If your server returns an error HTTP code, we will retry sending multiple times then abandon the message if all attempts failed." } } } }, "paymentProfile.created": { "post": { "tags": [ "Webhooks" ], "summary": "paymentProfile.created", "description": "Sent to your server when a Payment Profile is created", "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "eventType": { "type": "string", "const": "paymentProfile.created" }, "orgId": { "type": "string" }, "contactId": { "type": "string" }, "paymentProfileId": { "type": "string" } }, "required": [ "eventType", "orgId", "contactId", "paymentProfileId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Return a **200** status to indicate that the data was received successfully. If your server returns an error HTTP code, we will retry sending multiple times then abandon the message if all attempts failed." } } } }, "paymentProfile.updated": { "post": { "tags": [ "Webhooks" ], "summary": "paymentProfile.updated", "description": "Sent to your server when a Payment Profile is updated", "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "eventType": { "type": "string", "const": "paymentProfile.updated" }, "orgId": { "type": "string" }, "contactId": { "type": "string" }, "paymentProfileId": { "type": "string" } }, "required": [ "eventType", "orgId", "contactId", "paymentProfileId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Return a **200** status to indicate that the data was received successfully. If your server returns an error HTTP code, we will retry sending multiple times then abandon the message if all attempts failed." } } } } } }