--- openapi: 3.1.1 produces: - application/json info: title: Frame Payments Public API description: External-facing API endpoints for Frame Payments merchant integration version: v1 contact: name: Frame Payments API Support url: https://docs.framepayments.com email: support@framepayments.com paths: "/v1/accounts/{account_id}/beneficial_owners": get: summary: List beneficial owners tags: - Accounts description: Returns the beneficial-owner roster for a business account — every individual registered as an owner and/or controller, with their roles, ownership percentage, and verification status. Results include both directly-created owners and invited owners who completed their own details. operationId: listBeneficialOwners security: - BearerAuth: [] parameters: - name: account_id in: path required: true description: The ID of the business account whose roster to list. schema: type: string responses: '200': description: Returns the roster content: application/json: example: data: - id: 00000000-0000-4000-8000-000000000001 status: pending object: beneficial_owner account_id: 00000000-0000-4000-8000-000000000002 first_name: Ignacio middle_name: last_name: Kulas suffix: email: clint_wilderman@oconnell-mueller.test roles: - owner - controller percent_ownership: 50.0 created: 1745107200 updated: 1745107200 livemode: false schema: type: object properties: data: type: array items: "$ref": "#/components/schemas/BeneficialOwner" post: summary: Create beneficial owner tags: - Accounts description: 'Adds a beneficial owner to a business account''s roster. Pass `invite: true` to email the owner an invitation to complete their own identity details; when inviting, you only need name, email, and roles. Without an invite, supply the full identity payload directly (phone verification is waived for directly-created owners).' operationId: createBeneficialOwner security: - BearerAuth: [] parameters: - name: account_id in: path required: true description: The ID of the business account to add the owner to. schema: type: string responses: '201': description: Returns the new owner content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: completed object: beneficial_owner account_id: 00000000-0000-4000-8000-000000000002 first_name: Janet middle_name: last_name: Jones suffix: email: janet@example.com roles: - owner - controller percent_ownership: 50.0 created: 1745107200 updated: 1745107200 livemode: false schema: "$ref": "#/components/schemas/BeneficialOwner" requestBody: content: application/json: schema: type: object properties: invite: type: boolean example: true first_name: type: string example: Janet last_name: type: string example: Jones email: type: string example: janet@example.com dob: type: string example: '1988-06-15' ssn: type: string example: 123-45-6789 address_line1: type: string example: 12 New St city: type: string example: Austin state: type: string example: TX postal_code: type: string example: '78701' percent_ownership: type: number example: 50 roles: type: array items: type: string example: - owner - controller required: - first_name - last_name - email - roles required: true "/v1/accounts/{account_id}/beneficial_owners/{id}": get: summary: Show beneficial owner tags: - Accounts description: Retrieves a single beneficial owner by ID, scoped to the given business account. Returns the owner's identity details, roles, ownership percentage, and current verification status. operationId: getBeneficialOwner security: - BearerAuth: [] parameters: - name: account_id in: path required: true description: The ID of the business account the owner belongs to. schema: type: string - name: id in: path required: true description: The ID of the beneficial owner. schema: type: string responses: '200': description: Returns the owner content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: pending object: beneficial_owner account_id: 00000000-0000-4000-8000-000000000002 first_name: Shari middle_name: last_name: Daniel suffix: email: grisel@hoeger.test roles: - owner - controller percent_ownership: 50.0 created: 1745107200 updated: 1745107200 livemode: false schema: "$ref": "#/components/schemas/BeneficialOwner" patch: summary: Update beneficial owner tags: - Accounts description: |- Updates a beneficial owner's identity details, roles, or ownership percentage. Omitted fields are left unchanged; pass `roles` to replace the owner's role set. Blank values for identity fields (`email`, `phone_number`, `ssn`) and address fields are ignored rather than cleared — existing stored values are preserved. Verification status only moves forward: completing an owner's identity details upgrades their status, and updates never downgrade it or trigger a new invitation (use the resend-invite endpoint for that). operationId: updateBeneficialOwner security: - BearerAuth: [] parameters: - name: account_id in: path required: true description: The ID of the business account the owner belongs to. schema: type: string - name: id in: path required: true description: The ID of the beneficial owner to update. schema: type: string responses: '200': description: Returns the updated owner content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: pending object: beneficial_owner account_id: 00000000-0000-4000-8000-000000000002 first_name: Janet middle_name: last_name: Jones suffix: email: janet@example.com roles: - owner percent_ownership: 40.0 created: 1745107200 updated: 1745107200 livemode: false schema: "$ref": "#/components/schemas/BeneficialOwner" requestBody: content: application/json: schema: type: object properties: first_name: type: string example: Janet last_name: type: string example: Jones email: type: string example: janet@example.com ssn: type: string example: 123-45-6789 roles: type: array items: type: string example: - owner percent_ownership: type: number example: 40 delete: summary: Delete beneficial owner tags: - Accounts description: Removes a beneficial owner from the business account's roster. Returns `204 No Content` on success; any pending invitation for the owner is invalidated. operationId: deleteBeneficialOwner security: - BearerAuth: [] parameters: - name: account_id in: path required: true description: The ID of the business account the owner belongs to. schema: type: string - name: id in: path required: true description: The ID of the beneficial owner to remove. schema: type: string responses: '204': description: Removes the owner "/v1/accounts/{account_id}/beneficial_owners/{id}/resend_invite": post: summary: Resend beneficial owner invite tags: - Accounts description: 'Re-sends the invitation email to a beneficial owner who was created with `invite: true` but has not yet completed their identity details. Returns the owner object unchanged.' operationId: resendBeneficialOwnerInvite security: - BearerAuth: [] parameters: - name: account_id in: path required: true description: The ID of the business account the owner belongs to. schema: type: string - name: id in: path required: true description: The ID of the beneficial owner to re-invite. schema: type: string responses: '200': description: Returns the owner content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: invite_sent object: beneficial_owner account_id: 00000000-0000-4000-8000-000000000002 first_name: Janet middle_name: last_name: Jones suffix: email: janet@example.com roles: - owner - controller percent_ownership: created: 1745107200 updated: 1745107200 livemode: false schema: "$ref": "#/components/schemas/BeneficialOwner" "/v1/accounts/{account_id}/beneficial_owners/confirm": post: summary: Confirm roster tags: - Accounts description: |- Attests that the beneficial-owner roster for the business account is complete and accurate. Satisfies the account's `beneficial_owners_collected` onboarding requirement and records the attestation (with request IP and user agent) for compliance. Returns the updated account object. Fails with a validation error unless the roster has at least one person with the `owner` role, at least one with the `controller` role, and a combined ownership percentage of 100% or less. The roster remains editable after confirmation — confirm again after changes; each successful call re-stamps the recorded certification. operationId: confirmBeneficialOwnerRoster security: - BearerAuth: [] parameters: - name: account_id in: path required: true description: The ID of the business account whose roster to confirm. schema: type: string responses: '200': description: Returns the account content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: pending external_id: metadata: {} payout_payment_method_id: type: business object: account terms_of_service: profile: business: legal_business_name: Beer-Altenwerth doing_business_as: business_type: single_member_llc email: sammy@kuhn.example website: description: ein_last_four: mcc: naics: same_physical_and_legal_address: true phone: number: country_code: address: physical_address: capabilities: [] created: 1745107200 updated: 1745107200 livemode: false schema: "$ref": "#/components/schemas/Account" "/v1/accounts/{account_id}/kyc_prefill/confirm": post: summary: Confirm KYC prefill tags: - KYC Prefill operationId: confirmKycPrefill security: - BearerAuth: [] description: |- Records the account holder's confirmation of the KYC prefill data attached to an account. Use this endpoint at the end of a prefill flow — after Frame has populated the account holder's identity information from Prove (live mode) or from sandbox seed data — to mark that prefilled data as confirmed by the end user. The caller's IP address and user-agent are captured from the HTTP request as evidence of consent and stored on the account's individual record. On the first successful call, Frame emits the `frame.account.prefill.completed` webhook event; subsequent calls are idempotent and do not re-emit. Returns the updated account, including its current capabilities and any outstanding step fields. Returns `422` if the account does not have a KYC prefill record ready to confirm (e.g. prefill was never run, or the prefilled record is not in a confirmable state). parameters: - name: account_id in: path required: true description: ID of the account whose KYC prefill is being confirmed. schema: type: string responses: '200': description: Prefill confirmed. The account holder's prefilled identity is now linked to the account. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: pending external_id: metadata: {} payout_payment_method_id: type: individual object: account terms_of_service: profile: individual: email: paulette@fritsch-graham.test ssn_last_four: name: first_name: Jason middle_name: last_name: Brakus suffix: phone: number: country_code: address: birthdate: capabilities: [] created: 1745107200 updated: 1745107200 livemode: false schema: "$ref": "#/components/schemas/Account" '401': description: Unauthorized — missing or invalid API key. content: application/json: schema: "$ref": "#/components/schemas/AuthError" '404': description: Account not found, or account belongs to a different merchant. content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '422': description: The account has no KYC prefill record ready to confirm — for example, prefill was never run or the prefilled record is not in a confirmable state. content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" "/v1/accounts/{account_id}/geo_compliance": get: summary: Get account geo compliance status tags: - Geo Compliance description: |- Evaluates the account's most recent Sonar session and returns the current geocompliance status. Use this endpoint to check whether an account holder is currently in a restricted territory before initiating a transaction. Returns the current geocompliance status for the account, including the block reason and matched geofence if applicable. operationId: getAccountGeoCompliance x-frame-sdk: resource: accounts method: getGeoCompliance security: - BearerAuth: [] parameters: - name: account_id in: path description: Account ID required: true schema: type: string responses: '200': description: Clear — location is not within any restricted territory content: application/json: example: decision_id: 00000000-0000-4000-8000-000000000001 sonar_session_id: 00000000-0000-4000-8000-000000000002 evaluated_at: '2025-04-20T00:00:00Z' status: clear reason: no_location_data schema: type: object properties: sonar_session_id: type: string nullable: true description: ID of the SonarSession used to evaluate compliance decision_id: type: string nullable: true description: ID of the geo compliance decision record evaluated_at: type: string nullable: true description: ISO 8601 timestamp of when compliance was evaluated format: date-time status: type: string enum: - clear - blocked - unknown description: Geo compliance status for the account reason: type: string nullable: true enum: - restricted_territory - vpn_detected - no_location_data description: Reason for blocked or unknown status geofence: type: object nullable: true description: Geofence the account is blocked by (restricted_territory only) properties: id: type: string name: type: string required: - status '422': description: Geo compliance not enabled for merchant content: application/json: schema: type: object properties: error: type: object properties: type: type: string example: validation_error message: type: string '404': description: Account not found content: application/json: schema: type: object properties: error: type: object properties: type: type: string example: not_found message: type: string '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/accounts": get: summary: List accounts tags: - Accounts description: Returns a paginated list of accounts for your platform. Filter by `status`, `type`, or `external_id` to narrow results. Results are returned in reverse chronological order. operationId: listAccounts x-frame-sdk: resource: accounts method: list security: - BearerAuth: [] parameters: - name: page in: query description: Page number for pagination. Defaults to 1. required: false schema: type: integer - name: per_page in: query description: Number of results per page. Defaults to 10, maximum 100. required: false schema: type: integer - name: status in: query description: "Filter by account status. One of `active`, `pending`, `restricted`, or `disabled`.:\n * `active` \n * `pending` \n * `restricted` \n * `disabled` \n " required: false enum: - active - pending - restricted - disabled schema: type: string - name: type in: query description: Filter by account type. One of `individual` or `business`. required: false enum: - individual - business schema: type: string - name: external_id in: query description: Filter by your platform's external identifier. required: false schema: type: string - name: include_disabled in: query description: When `true`, includes disabled accounts in results. Defaults to `false`. required: false schema: type: boolean responses: '200': description: A paginated list of accounts. content: application/json: example: meta: page: 1 url: "/v1/accounts?status=" has_more: false prev: next: data: - id: 00000000-0000-4000-8000-000000000001 status: pending external_id: metadata: {} payout_payment_method_id: type: individual object: account terms_of_service: profile: individual: email: alana@price.test ssn_last_four: name: first_name: Giuseppe middle_name: last_name: Brakus suffix: phone: number: country_code: address: birthdate: capabilities: [] created: 1745107200 updated: 1745107200 livemode: false - id: 00000000-0000-4000-8000-000000000002 status: pending external_id: metadata: {} payout_payment_method_id: type: individual object: account terms_of_service: profile: individual: email: bobbye@bruen-lehner.test ssn_last_four: name: first_name: Santiago middle_name: last_name: Maggio suffix: phone: number: country_code: address: birthdate: capabilities: [] created: 1745107200 updated: 1745107200 livemode: false - id: 00000000-0000-4000-8000-000000000003 status: pending external_id: metadata: {} payout_payment_method_id: type: individual object: account terms_of_service: profile: individual: email: jewell@rath-wilkinson.example ssn_last_four: name: first_name: Alexandra middle_name: last_name: Streich suffix: phone: number: country_code: address: birthdate: capabilities: [] created: 1745107200 updated: 1745107200 livemode: false schema: type: object properties: data: type: array items: "$ref": "#/components/schemas/Account" meta: type: object properties: page: type: integer has_more: type: boolean next: type: string nullable: true prev: type: string nullable: true url: type: string '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" post: summary: Create account tags: - Accounts description: |- Creates a new account. Pass the account `type`, any `capabilities` to request, and known profile information. Frame validates the profile fields and immediately triggers any capability checks that can be resolved without additional information from the account holder. For capabilities that require further information — such as KYC — create an onboarding session after account creation to collect the remaining fields. operationId: createAccount x-frame-sdk: resource: accounts method: create security: - BearerAuth: [] parameters: [] responses: '201': description: Returns the newly created account object along with the current status of any requested capabilities. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: pending external_id: metadata: {} payout_payment_method_id: type: individual object: account terms_of_service: profile: individual: email: john.doe@example.com ssn_last_four: name: first_name: John middle_name: last_name: Doe suffix: phone: number: country_code: address: birthdate: capabilities: [] created: 1745107200 updated: 1745107200 livemode: false schema: "$ref": "#/components/schemas/Account" '422': description: Validation errors content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" requestBody: content: application/json: schema: type: object properties: type: type: string description: Account type. One of `individual` or `business`. enum: - individual - business example: individual capabilities: type: array description: Capability names to request for the account (e.g. `["kyc", "card_receive"]`). Pass an array of strings — not an array of objects. items: type: string example: - kyc - card_receive external_id: type: string description: An optional identifier from your own system. Must be unique per merchant. example: usr_8675309 terms_of_service: type: object description: Record of the account holder's acceptance of your platform's terms of service. properties: token: type: string description: An optional token identifying the specific version of terms accepted. example: tos_v1_2024 accepted_at: type: string format: date-time description: ISO 8601 timestamp of when the terms were accepted. example: '2024-08-24T14:15:22Z' ip_address: type: string description: IP address of the account holder at the time of acceptance. example: 192.168.1.1 user_agent: type: string description: User agent string from the account holder's browser at the time of acceptance. example: Mozilla/5.0 metadata: type: object description: A set of key-value pairs to attach to the account for your own reference. additionalProperties: true example: platform_user_id: u_123 profile: type: object description: Profile information for the account holder. Contains either an `individual` or `business` sub-object. properties: individual: type: object description: Individual profile. Either `email` or `phone` must be provided. properties: name: type: object description: Legal name of the account holder. properties: first_name: type: string description: First name. example: Marcia middle_name: type: string description: Middle name. example: last_name: type: string description: Last name. example: Longo suffix: type: string description: Name suffix (e.g. `Jr.`, `Sr.`). example: email: type: string format: email description: The individual's email address. example: marcia@example.com phone: type: object description: Phone number for the account holder. properties: number: type: string description: Phone number. example: '3107484186' country_code: type: string description: Country calling code (e.g. `"1"` for US). example: '1' address: type: object description: Residential address. properties: line_1: type: string description: Street address line 1. example: 123 Main St line_2: type: string description: Street address line 2. example: city: type: string description: City. example: Los Angeles state: type: string description: State or province code (e.g. `"CA"`). example: CA postal_code: type: string description: Postal or ZIP code. example: '90001' country: type: string description: Two-letter ISO country code (e.g. `"US"`). example: US birthdate: type: string format: date description: Date of birth in `YYYY-MM-DD` format. Required for KYC and age verification. example: '1982-07-19' ssn: type: string description: Full 9-digit Social Security Number. Stored encrypted — only the last four digits are returned via the API. example: '123456789' ssn_last_four: type: string description: Last four digits of the SSN, if the full SSN is not available. example: '6789' business: type: object description: Business profile. properties: legal_business_name: type: string description: The registered legal name of the business. example: Acme Corp doing_business_as: type: string description: Trade name (doing business as), if different from the legal name. example: business_type: type: string description: Business entity type (e.g. `llc`, `corporation`, `sole_proprietorship`). example: llc email: type: string format: email description: Business email address. example: billing@acme.com website: type: string description: The business's website URL. example: https://acme.com description: type: string description: A description of the business. example: phone: type: object description: Business phone number. properties: number: type: string description: Phone number. example: '2125550100' country_code: type: string description: Country calling code (e.g. `"1"` for US). example: '1' address: type: object description: Business legal address — the registered address of the business. properties: line_1: type: string description: Street address line 1. example: 100 Broadway line_2: type: string description: Street address line 2. example: Suite 200 city: type: string description: City. example: New York state: type: string description: State or province code (e.g. `"NY"`). example: NY postal_code: type: string description: Postal or ZIP code. example: '10005' country: type: string description: Two-letter ISO country code (e.g. `"US"`). example: US same_physical_and_legal_address: type: boolean description: Whether the business operates from its registered legal address. Defaults to `true`. When `true`, `physical_address` is ignored and the legal `address` is used as the physical address. Set to `false` when the business operates from a different location; the `physical_address` is then required to complete business information. example: true physical_address: type: object description: Business physical address — where the business actually operates. Only used when `same_physical_and_legal_address` is `false`; ignored otherwise. properties: line_1: type: string description: Street address line 1. example: 55 Market St line_2: type: string description: Street address line 2. example: Floor 3 city: type: string description: City. example: San Francisco state: type: string description: State or province code (e.g. `"CA"`). example: CA postal_code: type: string description: Postal or ZIP code. example: '94105' country: type: string description: Two-letter ISO country code (e.g. `"US"`). example: US ein: type: string description: 9-digit Employer Identification Number. Stored encrypted — only the last four digits are returned. example: mcc: type: string description: Merchant Category Code. example: '5734' naics: type: string description: NAICS industry classification code. example: '519130' required: - legal_business_name - business_type - email required: - type - profile "/v1/accounts/{id}": get: summary: Get account tags: - Accounts description: |- Retrieves an existing account by ID, including its profile and current capability statuses. Can be called with a secret key, or with a publishable key for client-side checkout. The publishable-key response omits `profile`, `metadata`, and `payout_payment_method_id`. operationId: getAccount x-frame-sdk: resource: accounts method: get security: - BearerAuth: [] - PublishableKey: [] parameters: - name: id in: path description: Account ID required: true schema: type: string responses: '200': description: Returns the account object with current capability statuses. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: pending external_id: metadata: {} payout_payment_method_id: type: individual object: account terms_of_service: profile: individual: email: rosia.wyman@lakin.test ssn_last_four: name: first_name: Alita middle_name: last_name: Will suffix: phone: number: country_code: address: birthdate: capabilities: [] created: 1745107200 updated: 1745107200 livemode: false schema: "$ref": "#/components/schemas/Account" '404': description: Account not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" patch: summary: Update account tags: - Accounts description: Updates an existing account. You can update profile information, metadata, and terms of service acceptance. Updating profile fields required for pending capabilities triggers those checks to re-run automatically. operationId: updateAccount x-frame-sdk: resource: accounts method: update security: - BearerAuth: [] parameters: - name: id in: path description: Account ID required: true schema: type: string responses: '200': description: Returns the updated account object with current capability statuses. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: pending external_id: ext_updated_123 metadata: {} payout_payment_method_id: type: individual object: account terms_of_service: profile: individual: email: updated@example.com ssn_last_four: name: first_name: Tamatha middle_name: last_name: Brown suffix: phone: number: country_code: address: birthdate: capabilities: [] created: 1745107200 updated: 1745107200 livemode: false schema: "$ref": "#/components/schemas/Account" '404': description: Account not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" requestBody: content: application/json: schema: type: object properties: external_id: type: string description: An identifier from your own system to associate with the account. Must be unique per merchant. example: usr_8675309 metadata: type: object description: A set of key-value pairs to attach to the account for your own reference. additionalProperties: true example: platform_user_id: u_123 terms_of_service: type: object description: Record of the account holder's acceptance of your platform's terms of service. properties: token: type: string description: An optional token identifying the specific version of terms accepted. example: tos_v1_2024 accepted_at: type: string format: date-time description: ISO 8601 timestamp of when the terms were accepted. example: '2024-08-24T14:15:22Z' ip_address: type: string description: IP address of the account holder at the time of acceptance. example: 192.168.1.1 user_agent: type: string description: User agent string from the account holder's browser at the time of acceptance. example: Mozilla/5.0 profile: type: object description: Updated profile information for the account holder. Contains either an `individual` or `business` sub-object. properties: individual: type: object description: Individual profile fields to update. properties: name: type: object description: Legal name of the account holder. properties: first_name: type: string description: First name. example: Riley middle_name: type: string description: Middle name. example: last_name: type: string description: Last name. example: Morgan suffix: type: string description: Name suffix (e.g. `Jr.`, `Sr.`). example: email: type: string format: email description: The individual's email address. example: riley@example.com phone: type: object description: Phone number for the account holder. properties: number: type: string description: Phone number. example: '3107484186' country_code: type: string description: Country calling code (e.g. `"1"` for US). example: '1' address: type: object description: Residential address. properties: line_1: type: string description: Street address line 1. example: 123 Main St line_2: type: string description: Street address line 2. example: city: type: string description: City. example: Los Angeles state: type: string description: State or province code (e.g. `"CA"`). example: CA postal_code: type: string description: Postal or ZIP code. example: '90001' country: type: string description: Two-letter ISO country code (e.g. `"US"`). example: US birthdate: type: string format: date description: Date of birth in `YYYY-MM-DD` format. example: '1982-07-19' ssn: type: string description: Full 9-digit Social Security Number. Stored encrypted — only the last four digits are returned. example: ssn_last_four: type: string description: Last four digits of the SSN, if the full SSN is not available. example: '6789' business: type: object description: Business profile fields to update. properties: legal_business_name: type: string description: The registered legal name of the business. example: Acme Corp doing_business_as: type: string description: Trade name (doing business as), if different from the legal name. example: business_type: type: string description: Business entity type (e.g. `llc`, `corporation`, `sole_proprietorship`). example: llc email: type: string format: email description: Business email address. example: billing@acme.com website: type: string description: The business's website URL. example: https://acme.com description: type: string description: A description of the business. example: phone: type: object description: Business phone number. properties: number: type: string description: Phone number. example: '2125550100' country_code: type: string description: Country calling code (e.g. `"1"` for US). example: '1' address: type: object description: Business legal address — the registered address of the business. properties: line_1: type: string description: Street address line 1. example: 100 Broadway line_2: type: string description: Street address line 2. example: Suite 200 city: type: string description: City. example: New York state: type: string description: State or province code (e.g. `"NY"`). example: NY postal_code: type: string description: Postal or ZIP code. example: '10005' country: type: string description: Two-letter ISO country code (e.g. `"US"`). example: US same_physical_and_legal_address: type: boolean description: Whether the business operates from its registered legal address. Defaults to `true`. When `true`, `physical_address` is ignored and the legal `address` is used as the physical address. Set to `false` when the business operates from a different location; the `physical_address` is then required to complete business information. example: true physical_address: type: object description: Business physical address — where the business actually operates. Only used when `same_physical_and_legal_address` is `false`; ignored otherwise. properties: line_1: type: string description: Street address line 1. example: 55 Market St line_2: type: string description: Street address line 2. example: Floor 3 city: type: string description: City. example: San Francisco state: type: string description: State or province code (e.g. `"CA"`). example: CA postal_code: type: string description: Postal or ZIP code. example: '94105' country: type: string description: Two-letter ISO country code (e.g. `"US"`). example: US ein: type: string description: 9-digit Employer Identification Number. Stored encrypted — only the last four digits are returned. example: mcc: type: string description: Merchant Category Code. example: '5734' naics: type: string description: NAICS industry classification code. example: '519130' delete: summary: Disable account tags: - Accounts description: Disables an account. Disabled accounts cannot initiate or receive payments and all associated capabilities are suspended. This is a soft delete — the account record is retained. Contact Frame support to re-enable a disabled account. operationId: disableAccount x-frame-sdk: resource: accounts method: disable security: - BearerAuth: [] parameters: - name: id in: path description: Account ID required: true schema: type: string responses: '200': description: Returns the disabled account object. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: disabled external_id: metadata: {} payout_payment_method_id: type: individual object: account terms_of_service: profile: individual: email: lucius.klocko@keebler.test ssn_last_four: name: first_name: Emilio middle_name: last_name: McGlynn suffix: phone: number: country_code: address: birthdate: capabilities: [] created: 1745107200 updated: 1745107200 livemode: false schema: "$ref": "#/components/schemas/Account" '404': description: Account not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/accounts/search": get: summary: Search accounts tags: - Accounts description: Search accounts with advanced filters. Supports filtering by email (partial match), external ID, type, status, and creation date range. operationId: searchAccounts x-frame-sdk: resource: accounts method: search security: - BearerAuth: [] parameters: - name: email in: query description: Filter by email address (partial match). required: false schema: type: string - name: external_id in: query description: Filter by your platform's external identifier. required: false schema: type: string - name: type in: query description: "Filter by account type. One of `individual` or `business`.:\n * `individual` \n * `business` \n " required: false enum: - individual - business schema: type: string - name: status in: query description: Filter by account status. One of `active`, `pending`, `restricted`, or `disabled`. required: false enum: - active - pending - restricted - disabled schema: type: string - name: created_before in: query description: Return only accounts created before this Unix timestamp. required: false schema: type: integer - name: created_after in: query description: Return only accounts created after this Unix timestamp. required: false schema: type: integer responses: '200': description: A paginated list of matching accounts. content: application/json: example: meta: page: 1 url: "/v1/accounts/search?status=" has_more: false prev: next: data: - id: 00000000-0000-4000-8000-000000000001 status: active external_id: metadata: {} payout_payment_method_id: type: individual object: account terms_of_service: profile: individual: email: marlon@dickinson.test ssn_last_four: name: first_name: Alonzo middle_name: last_name: Blick suffix: phone: number: country_code: address: birthdate: capabilities: [] created: 1745107200 updated: 1745107200 livemode: false schema: type: object properties: data: type: array items: "$ref": "#/components/schemas/Account" meta: type: object properties: page: type: integer has_more: type: boolean '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/accounts/{id}/payment_methods": get: summary: List account payment methods tags: - Accounts description: |- Returns a paginated list of payment methods attached to a specific account. Can be called with a secret key, or with a publishable key for client-side checkout. operationId: listAccountPaymentMethods x-frame-sdk: resource: accounts method: getPaymentMethods security: - BearerAuth: [] - PublishableKey: [] parameters: - name: id in: path description: Account ID required: true schema: type: string responses: '200': description: A paginated list of payment methods for the account. content: application/json: example: meta: page: 1 url: "/v1/accounts/00000000-0000-4000-8000-000000000001/payment_methods" has_more: false prev: next: data: - id: 00000000-0000-4000-8000-000000000002 customer_id: account_id: 00000000-0000-4000-8000-000000000001 billing: type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '09' exp_year: '30' issuer: currency: segment: type: last_four: '4242' schema: type: object properties: data: type: array items: "$ref": "#/components/schemas/PaymentMethod" meta: type: object properties: page: type: integer has_more: type: boolean '404': description: Account not found '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/accounts/{id}/restrict": post: summary: Restrict account tags: - Accounts description: Restricts an account, preventing it from initiating or receiving payments. The account record is retained and can be unrestricted. Use this for temporary holds — use disable for permanent deactivation. operationId: restrictAccount x-frame-sdk: resource: accounts method: restrict security: - BearerAuth: [] parameters: - name: id in: path description: Account ID required: true schema: type: string responses: '200': description: Returns the restricted account object. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: restricted external_id: metadata: {} payout_payment_method_id: type: individual object: account terms_of_service: profile: individual: email: bridgette@runte-stark.test ssn_last_four: name: first_name: Henry middle_name: last_name: King suffix: phone: number: country_code: address: birthdate: capabilities: [] created: 1745107200 updated: 1745107200 livemode: false schema: "$ref": "#/components/schemas/Account" '422': description: Validation error - account already restricted or disabled '404': description: Account not found '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/accounts/{id}/unrestrict": post: summary: Unrestrict account tags: - Accounts description: Removes a restriction from an account, restoring it to its previous active state and re-enabling payments. operationId: unrestrictAccount x-frame-sdk: resource: accounts method: unrestrict security: - BearerAuth: [] parameters: - name: id in: path description: Account ID required: true schema: type: string responses: '200': description: Returns the account object with its restriction removed. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: active external_id: metadata: {} payout_payment_method_id: type: individual object: account terms_of_service: profile: individual: email: clement_wyman@muller-mills.example ssn_last_four: name: first_name: Shanelle middle_name: last_name: Walsh suffix: phone: number: country_code: address: birthdate: capabilities: [] created: 1745107200 updated: 1745107200 livemode: false schema: "$ref": "#/components/schemas/Account" '422': description: Validation error - account is not restricted '404': description: Account not found '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/accounts/{account_id}/phone_verifications": post: summary: Create phone verification tags: - Phone Verifications description: |- Initiates a phone verification for the given account by sending a one-time passcode (OTP) via SMS to the account's phone number. frameOS evaluates mobile identity signals in the background — including the number's trust score, carrier information, and behavioral characteristics — to determine whether the user presents a risk. If you are using onboarding sessions, frameOS handles the full OTP flow — sending, delivery, and validation — with no additional integration required. Call this endpoint directly only when managing the verification flow outside of an onboarding session. operationId: createPhoneVerification x-frame-sdk: resource: phoneVerifications method: create security: - BearerAuth: [] parameters: - name: account_id in: path description: The ID of the account to initiate phone verification for. required: true schema: type: string responses: '201': description: Phone verification created and OTP sent to the account's phone number. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 type: phone status: pending provider: sandbox sandbox: expected_codes: - '123456' - '000000' - '111111' schema: type: object properties: id: type: string description: Verification ID type: type: string example: phone description: Verification type status: type: string description: Current status of the verification. Will be `pending` until the OTP is confirmed. enum: - pending - verified - expired - failed example: pending required: - id - type - status '404': description: Account not found '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" '422': description: Validation error — for example, the phone number format is invalid or the OTP could not be sent. content: application/json: schema: type: object properties: status: type: integer error: type: string code: type: string error_details: type: string requestBody: content: application/json: schema: type: object properties: type: type: string description: Verification type (e.g. twilio, prove) phone_number: type: string description: The phone number to verify. This is the number that will receive the OTP and be linked to the account holder's identity within Frame. date_of_birth: type: string format: date description: Date of birth (saved to account profile if provided) "/v1/accounts/{account_id}/phone_verifications/{id}/confirm": post: summary: Confirm phone verification tags: - Phone Verifications description: |- Confirms a phone verification by validating the OTP code sent to the account's phone number. If the code is correct and has not expired, the phone number is linked to the account holder's identity within Frame and the verification status transitions to `verified`. If the number passes verification, the account holder is authenticated and their phone number is linked to their identity. If the number shows suspicious characteristics, additional verification steps may be introduced or the evaluation may be flagged for review. operationId: confirmPhoneVerification x-frame-sdk: resource: phoneVerifications method: confirm security: - BearerAuth: [] parameters: - name: account_id in: path description: The ID of the account the phone verification belongs to. required: true schema: type: string - name: id in: path description: The ID of the phone verification to confirm. required: true schema: type: string responses: '200': description: Phone verification confirmed. The phone number is now linked to the account holder's identity and the verification status is `verified`. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: verified provider: twilio schema: type: object properties: id: type: string description: Verification ID status: type: string description: Verification status after confirmation. enum: - verified example: verified required: - id - status '404': description: Account or verification not found '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" '422': description: Invalid or expired OTP code. content: application/json: schema: type: object properties: status: type: integer error: type: string code: type: string error_details: type: string requestBody: content: application/json: schema: type: object properties: code: type: string description: The one-time passcode (OTP) sent via SMS to the account holder's phone number. "/v1/bank_accounts": post: summary: Create bank account tags: - Bank Accounts description: Create a bank account for a customer or account using a processor token (e.g. from Plaid). operationId: createBankAccount security: - BearerAuth: [] parameters: [] responses: '201': description: Bank account created successfully content: application/json: example: id: 00000000-0000-4000-8000-000000000001 routing_number: '021000021' account_number_last_4: '4242' account_type: checking bank_name: processor_name: plaid status: pending object: bank_account customer_id: 00000000-0000-4000-8000-000000000002 account_id: created: 1745107200 updated: 1745107200 livemode: false schema: type: object properties: id: type: string object: type: string example: bank_account routing_number: type: string account_number_last_4: type: string account_type: type: string description: checking or savings bank_name: type: string nullable: true processor_name: type: string nullable: true status: type: string customer_id: type: string nullable: true account_id: type: string nullable: true livemode: type: boolean created: type: integer updated: type: integer required: - id - object - routing_number - account_number_last_4 - account_type - status - livemode - created - updated '422': description: Validation error content: application/json: schema: type: object properties: status: type: integer error: type: string code: type: string error_details: type: object '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" requestBody: content: application/json: schema: type: object properties: processor: type: string description: Processor name (e.g. plaid) example: plaid processor_token: type: string description: Token from the processor (e.g. Plaid public token) customer_id: type: string nullable: true description: Customer ID to attach the bank account to (mutually exclusive with account_id) account_id: type: string nullable: true description: Account ID to attach the bank account to (mutually exclusive with customer_id) required: - processor - processor_token "/v1/billing/billing_credit": post: summary: Issue a billing credit tags: - Billing description: |- Issues billing credits to a customer that can be used to offset future billing charges. Billing credits enable you to allocate credits to customers that can be applied against future billing charges. Credits can be linked to specific products, have expiration dates, and track usage over time. When credits are exhausted, Frame fires the `billing_credit.exhausted` webhook event. operationId: createBillingCredit x-frame-sdk: resource: billing method: createBillingCredit security: - BearerAuth: [] parameters: - name: customer in: query required: false description: The unique identifier (UUID) of the customer to issue credits to. Mutually exclusive with account. schema: type: string - name: account in: query required: false description: Account ID to issue credits to. Mutually exclusive with customer. schema: type: string - name: product in: query required: true description: The unique identifier (UUID) of the product or billing plan this credit is linked to. schema: type: string - name: billing_credits in: query required: true description: The number of billing credits to allocate to the customer. schema: type: integer - name: expires in: query required: true description: The date when the billing credits expire and can no longer be used, in ISO 8601 format. schema: type: string - name: limited in: query required: false description: Whether the credit pool is capped at the allocated amount. schema: type: boolean responses: '200': description: Returns the created billing credit object if successful. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 billing_credits: '49.49' available_credits: '49.49' used_credits: '0.0' status: active watchlist: false product: 00000000-0000-4000-8000-000000000002 customer: 00000000-0000-4000-8000-000000000003 account: account_id: object: billing_credit created: 1745107200 updated: 1745107200 livemode: false expires: 1744300775 schema: type: object properties: id: type: string object: type: string example: billing_credit customer: type: string nullable: true description: Customer ID this credit is issued to account: type: string nullable: true description: Account ID this credit is issued to product: type: string nullable: true description: Product ID this credit is linked to billing_credits: type: string description: Total credits allocated available_credits: type: string description: Credits remaining used_credits: type: string description: Credits consumed status: type: string description: Credit status (e.g. active) watchlist: type: boolean description: Whether this credit is flagged for monitoring expires: type: integer nullable: true description: Unix timestamp when credits expire livemode: type: boolean created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - billing_credits - available_credits - used_credits - status - watchlist - livemode - created - updated '422': description: Validation error content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/billing/billing_credit/{id}": get: summary: Retrieve billing credit usage tags: - Billing description: Retrieves the billing credits for a specific customer, including available and consumed credit balances. Returns the billing credit object if found, or an error if the customer has no billing credits. operationId: getBillingCredit x-frame-sdk: resource: billing method: getBillingCredit security: - BearerAuth: [] parameters: - name: id in: path required: true description: Billing credit ID schema: type: string responses: '200': description: Returns the billing credit object with available and consumed credit balances. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 billing_credits: '47.78' available_credits: '47.78' used_credits: '0.0' status: active watchlist: false product: 00000000-0000-4000-8000-000000000002 customer: 00000000-0000-4000-8000-000000000003 account: account_id: object: billing_credit created: 1745107200 updated: 1745107200 livemode: false expires: 1744531575 schema: type: object properties: id: type: string object: type: string example: billing_credit customer: type: string nullable: true description: Customer ID this credit is issued to account: type: string nullable: true description: Account ID this credit is issued to product: type: string nullable: true description: Product ID this credit is linked to billing_credits: type: string description: Total credits allocated available_credits: type: string description: Credits remaining used_credits: type: string description: Credits consumed status: type: string description: Credit status (e.g. active) watchlist: type: boolean description: Whether this credit is flagged for monitoring expires: type: integer nullable: true description: Unix timestamp when credits expire livemode: type: boolean created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - billing_credits - available_credits - used_credits - status - watchlist - livemode - created - updated '422': description: Error retrieving credit content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/billing/billing_invoice": post: summary: Generate invoice from billing report tags: - Billing description: |- Generates an invoice from a billing report period. Use this to convert accumulated billing metric usage into a chargeable invoice for postpaid billing or when credits are exhausted. Line items are automatically populated from the usage events in the specified date range. operationId: createBillingInvoice x-frame-sdk: resource: billing method: createBillingInvoice security: - BearerAuth: [] parameters: - name: customer in: query required: false description: Customer ID to generate the invoice for. Mutually exclusive with account. schema: type: string - name: account in: query required: false description: Account ID to generate the invoice for. Mutually exclusive with customer. schema: type: string - name: start_date in: query required: true description: Start date of the billing period in ISO 8601 format. schema: type: string - name: end_date in: query required: true description: End date of the billing period in ISO 8601 format. schema: type: string - name: collection_method in: query required: false enum: - request_payment - charge_automatically description: "How payment is collected. `request_payment` sends the invoice to the customer for manual payment; `charge_automatically` immediately charges their default payment method.:\n * `request_payment` \n * `charge_automatically` \n " schema: type: string - name: description in: query required: false description: A description for the invoice. schema: type: string - name: memo in: query required: false description: A memo or note to include on the invoice. schema: type: string - name: net_terms in: query required: false description: Payment terms in days. schema: type: integer - name: events in: query required: false description: Comma-separated billing metric event names to include in the invoice. schema: type: string responses: '200': description: Returns the generated invoice object with line items populated from the usage events in the specified date range. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 invoice_number: '1' collection_method: request_payment billing_reason: status: draft due_date: description: Invoice description memo: net_terms: 0 subscription_id: object: invoice total: 1000 currency: USD livemode: false created: 1745107200 updated: 1745107200 metadata: {} customer: id: 00000000-0000-4000-8000-000000000002 name: Deadra Lesch email: customer@frame.com description: deserunt status: active date_of_birth: phone: "+13107484186" payment_methods: [] billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} line_items: [] schema: "$ref": "#/components/schemas/Invoice" '400': description: Validation error content: application/json: schema: "$ref": "#/components/schemas/ValidationError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/billing/report/customer": get: summary: Get usage report for a customer tags: - Billing description: |- Generates a billing report for a specific customer within a given time range. Billing reports aggregate customer usage data across billing metrics, providing a detailed breakdown of consumption during a billing period. Provide either customer or account — not both. operationId: getCustomerBillingReport x-frame-sdk: resource: billing method: getCustomerReport security: - BearerAuth: [] parameters: - name: customer in: query required: false description: The ID of the customer to get the report for. Mutually exclusive with account. schema: type: string - name: account in: query required: false description: Account ID to get the report for. Mutually exclusive with customer. schema: type: string - name: from in: query required: true description: Start date for the report period in ISO 8601 format. schema: type: string - name: to in: query required: true description: End date for the report period in ISO 8601 format. schema: type: string responses: '200': description: Returns a billing report object with aggregated usage for the customer. content: application/json: example: aggregated_usage: [] customer: account: account_id: usage: '0.0' livemode: false schema: type: object description: Aggregated usage report across one or more billing metrics properties: aggregated_usage: type: array items: type: object properties: object: type: string example: billing_report aggregation: type: string enum: - sum - average - count - count_unique event_name: type: string usage: type: string description: Total usage as a decimal string billing_metric: type: string description: ID of the billing metric customer: type: string nullable: true account: type: string nullable: true usage: type: string description: Total aggregated usage as a decimal string livemode: type: boolean required: - aggregated_usage - usage - livemode '422': description: Validation error — both customer and account provided content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/billing/report/event/{event_name}": get: summary: Get usage report for a specific billing metric tags: - Billing description: Generates a report for a specific billing event within a given time range. Returns a billing report object for the specified event. operationId: getBillingMetricReport x-frame-sdk: resource: billing method: getEventReport security: - BearerAuth: [] parameters: - name: event_name in: path required: true description: The name of the billing event to generate the report for. schema: type: string - name: customer in: query required: false description: The ID of the customer to filter the report by. schema: type: string - name: start_date in: query required: true description: Start date for the report period in ISO 8601 format. schema: type: string - name: end_date in: query required: true description: End date for the report period in ISO 8601 format. schema: type: string responses: '200': description: Returns a billing report object for the specified event. content: application/json: example: object: billing_report aggregation: sum event_name: 00000000-0000-4000-8000-000000000001 usage: '0.0' billing_metric: 00000000-0000-4000-8000-000000000002 customer: account: account_id: livemode: false schema: type: object description: Usage report for a single billing metric properties: object: type: string example: billing_report aggregation: type: string event_name: type: string usage: type: string billing_metric: type: string customer: type: string nullable: true account: type: string nullable: true livemode: type: boolean required: - object - aggregation - event_name - usage - billing_metric - livemode '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/billing/report/events": get: summary: Get usage report for multiple billing metrics tags: - Billing description: Generates reports for multiple billing events within a given time range. Returns aggregated usage for multiple billing metric event types in a single call. Pass event names as a comma-separated query parameter. operationId: getBillingMetricsReport x-frame-sdk: resource: billing method: getEventsReport security: - BearerAuth: [] parameters: - name: events in: query required: true description: Comma-separated list of event names to include in the report (e.g. api_call,storage_gb). schema: type: string - name: customer in: query required: false description: The ID of the customer to get the report for. schema: type: string - name: start_date in: query required: true description: Start date for the report period in ISO 8601 format. schema: type: string - name: end_date in: query required: true description: End date for the report period in ISO 8601 format. schema: type: string responses: '200': description: Returns a billing report object with aggregated usage for the specified events. content: application/json: example: aggregated_usage: [] customer: account: account_id: usage: '0.0' livemode: false schema: type: object description: Aggregated usage report across one or more billing metrics properties: aggregated_usage: type: array items: type: object properties: object: type: string example: billing_report aggregation: type: string enum: - sum - average - count - count_unique event_name: type: string usage: type: string description: Total usage as a decimal string billing_metric: type: string description: ID of the billing metric customer: type: string nullable: true account: type: string nullable: true usage: type: string description: Total aggregated usage as a decimal string livemode: type: boolean required: - aggregated_usage - usage - livemode '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/billing/report/subscription": get: summary: Get usage report for a subscription tags: - Billing description: Returns the billing report for a specific subscription in the current subscription period. Provides aggregated billing metric usage for the subscription. operationId: getSubscriptionBillingReport x-frame-sdk: resource: billing method: getSubscriptionReport security: - BearerAuth: [] parameters: - name: subscription in: query required: true description: The ID of the subscription to get the report for. schema: type: string responses: '200': description: Returns a billing report object with aggregated usage for the subscription. content: application/json: example: aggregated_usage: [] customer: account: account_id: usage: '0.0' livemode: false schema: type: object description: Aggregated usage report across one or more billing metrics properties: aggregated_usage: type: array items: type: object properties: object: type: string example: billing_report aggregation: type: string enum: - sum - average - count - count_unique event_name: type: string usage: type: string description: Total usage as a decimal string billing_metric: type: string description: ID of the billing metric customer: type: string nullable: true account: type: string nullable: true usage: type: string description: Total aggregated usage as a decimal string livemode: type: boolean required: - aggregated_usage - usage - livemode '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/billing/report/threshold_progress": get: summary: Get threshold progress for a customer or account tags: - Billing description: Returns how close a customer or account is to hitting a billing threshold. Billing events accumulate as pending charges and this endpoint tracks progress toward the auto-charge threshold. Provide either customer or account — not both. operationId: getBillingThresholdProgress security: - BearerAuth: [] parameters: - name: customer in: query required: false description: Customer ID (mutually exclusive with account) schema: type: string - name: account in: query required: false description: Account ID (mutually exclusive with customer) schema: type: string responses: '200': description: Returns a threshold progress object showing accumulated charges, the threshold target, and progress percentage. content: application/json: example: object: threshold_progress accumulated_amount_cents: 5000 threshold_amount_cents: 10000 threshold_percentage: 50.0 oldest_pending_charge_at: period_start: '2025-03-21T00:00:00Z' period_end: '2025-04-20T00:00:00Z' billing_cycle: monthly customer: account: account_id: livemode: false schema: type: object properties: object: type: string example: threshold_progress accumulated_amount_cents: type: integer description: Amount accumulated toward the threshold in cents threshold_amount_cents: type: integer nullable: true description: Threshold target in cents threshold_percentage: type: number nullable: true description: Progress toward threshold as a percentage (0–100) oldest_pending_charge_at: type: string nullable: true description: ISO 8601 timestamp of the oldest pending charge period_start: type: string nullable: true description: ISO 8601 start of the billing period period_end: type: string nullable: true description: ISO 8601 end of the billing period billing_cycle: type: string nullable: true customer: type: string nullable: true account: type: string nullable: true livemode: type: boolean required: - object - accumulated_amount_cents - livemode '422': description: Validation error — both customer and account provided content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/billing/metering_events": post: summary: Record a billing metric event tags: - Billing description: |- Creates a new billing metric event to track customer usage. Billing metric events are discrete instances of a customer's usage for a given billing metric. Include a `reference` field as an idempotency key to prevent duplicate charges — submitting a duplicate reference for the same event_name is silently ignored, making it safe to retry. operationId: createBillingMetricEvent x-frame-sdk: resource: billing method: createMeteringEvent security: - BearerAuth: [] parameters: - name: event_name in: query required: true description: The name of the billing meter this event is associated with. schema: type: string - name: reference in: query required: true description: A unique reference for this event. Acts as an idempotency key — duplicate references for the same event_name are silently ignored. schema: type: string - name: customer in: query required: true description: The ID of the customer this event is associated with. schema: type: string - name: value in: query required: true description: The measured value for this event (e.g. 1.0 for a single API call, 2.5 for GB of storage). schema: type: number - name: timestamp in: query required: false description: The time when this event occurred in ISO 8601 format. Defaults to current time if not provided. schema: type: string - name: markup_percentage in: query required: false description: A percentage markup applied for calculations. schema: type: number responses: '200': description: Returns the created billing metric event object. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 reference: evt_0000000000000001 value: '1.0' timestamp: '2025-04-20T00:00:00.000Z' customer: 00000000-0000-4000-8000-000000000002 billing_metric: 00000000-0000-4000-8000-000000000003 object: billing_metric_event created: 1745107200 updated: 1745107200 livemode: false schema: type: object properties: id: type: string object: type: string example: billing_metric_event reference: type: string description: Idempotency key — duplicate events with the same reference are ignored value: type: string description: Measured value for this event, serialized as decimal string (e.g. '1.5') timestamp: type: string description: ISO 8601 timestamp of when the event occurred. Defaults to ingestion time if not provided. customer: type: string nullable: true description: ID of the customer this event is associated with billing_metric: type: string description: ID of the billing metric this event contributes to livemode: type: boolean created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - reference - value - billing_metric - livemode - created - updated '400': description: Validation error content: application/json: schema: "$ref": "#/components/schemas/ValidationError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/billing/metering_events/{id}": get: summary: Retrieve a billing metric event tags: - Billing description: Retrieves the details of an existing billing metric event using the event's ID or reference key. Returns the billing metric event object if found, or an error if the event doesn't exist. operationId: getBillingMetricEvent x-frame-sdk: resource: billing method: getMeteringEvent security: - BearerAuth: [] parameters: - name: id in: path required: true description: The ID or reference key of the billing metric event to retrieve. schema: type: string responses: '200': description: Returns the billing metric event object. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 reference: ewsrwfgwgs value: '3743.89' timestamp: '2025-04-09T03:59:28.000Z' customer: 00000000-0000-4000-8000-000000000002 billing_metric: 00000000-0000-4000-8000-000000000003 object: billing_metric_event created: 1745107200 updated: 1745107200 livemode: false schema: type: object properties: id: type: string object: type: string example: billing_metric_event reference: type: string description: Idempotency key — duplicate events with the same reference are ignored value: type: string description: Measured value for this event, serialized as decimal string (e.g. '1.5') timestamp: type: string description: ISO 8601 timestamp of when the event occurred. Defaults to ingestion time if not provided. customer: type: string nullable: true description: ID of the customer this event is associated with billing_metric: type: string description: ID of the billing metric this event contributes to livemode: type: boolean created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - reference - value - billing_metric - livemode - created - updated '404': description: Event not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" patch: summary: Update a billing metric event tags: - Billing description: Updates the specified billing metric event by setting the values of the parameters passed. Returns the updated billing metric event object if successful, or an error if the event doesn't exist or the update fails. operationId: updateBillingMetricEvent x-frame-sdk: resource: billing method: updateMeteringEvent security: - BearerAuth: [] parameters: - name: id in: path required: true description: The ID or reference key of the billing metric event to update. schema: type: string - name: value in: query required: false description: The new measured value for this event. schema: type: number - name: reference in: query required: false description: The reference key to identify the event. schema: type: string responses: '200': description: Returns the updated billing metric event object. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 reference: sfdwlmzvyq value: '5.0' timestamp: '2025-04-11T07:31:55.000Z' customer: 00000000-0000-4000-8000-000000000002 billing_metric: 00000000-0000-4000-8000-000000000003 object: billing_metric_event created: 1745107200 updated: 1745107200 livemode: false schema: type: object properties: id: type: string object: type: string example: billing_metric_event reference: type: string description: Idempotency key — duplicate events with the same reference are ignored value: type: string description: Measured value for this event, serialized as decimal string (e.g. '1.5') timestamp: type: string description: ISO 8601 timestamp of when the event occurred. Defaults to ingestion time if not provided. customer: type: string nullable: true description: ID of the customer this event is associated with billing_metric: type: string description: ID of the billing metric this event contributes to livemode: type: boolean created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - reference - value - billing_metric - livemode - created - updated '400': description: Event not found content: application/json: schema: "$ref": "#/components/schemas/ValidationError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/billing/metering": post: summary: Create a billing metric tags: - Billing description: |- Creates a new billing meter that can be used to track and bill for specific events or actions. Billing meters are unique customer actions that can be tracked and billed within your app. Each meter has a unique event_name that metering events reference when recording usage. operationId: createBillingMetric x-frame-sdk: resource: billing method: createMetering security: - BearerAuth: [] parameters: - name: event_name in: query required: true description: The name of the billing event or trigger. Must be unique across your account. schema: type: string - name: aggregation in: query required: true enum: - sum - average - count - count_unique description: "Defines how multiple occurrences are combined. One of `sum`, `average`, `count`, or `count_unique`. Use `count_unique` to deduplicate by idempotency key.:\n * `sum` \n * `average` \n * `count` \n * `count_unique` \n " schema: type: string - name: display_name in: query required: false description: A human-readable label for this billing meter, displayed in the dashboard. schema: type: string - name: description in: query required: false description: A brief description of what this billing meter tracks. schema: type: string - name: value in: query required: false description: The amount associated with this billing event. For count-based meters, this is typically 1.0. schema: type: number - name: markup_percentage in: query required: false description: A percentage markup applied for calculations. For example, 2.5 for a 2.5% markup. schema: type: number responses: '200': description: Returns the newly created billing meter object. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: active aggregation: count event_name: api_call description: Counts each API call made by the customer display_name: API Calls value: '0.0' object: billing_metric created: 1745107200 updated: 1745107200 livemode: false schema: type: object properties: id: type: string object: type: string example: billing_metric event_name: type: string description: Unique name identifying this billing metric (e.g. api_call, storage_gb) display_name: type: string description: Human-readable label shown in reports description: type: string nullable: true aggregation: type: string enum: - sum - average - count - count_unique description: How usage events are aggregated. 'count_unique' deduplicates by reference/idempotency key. value: type: string nullable: true description: Default value applied to events that don't specify their own (serialized as decimal string, e.g. '1.5') status: type: string enum: - active - inactive - pending livemode: type: boolean created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - event_name - aggregation - status - livemode - created - updated '400': description: Validation error content: application/json: schema: "$ref": "#/components/schemas/ValidationError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/billing/metering/{id}": get: summary: Retrieve a billing metric tags: - Billing description: Retrieves the details of an existing billing meter. Returns the billing meter object if a valid ID was provided, or an error if the billing meter doesn't exist. operationId: getBillingMetric x-frame-sdk: resource: billing method: getMetering security: - BearerAuth: [] parameters: - name: id in: path required: true description: Billing metric ID schema: type: string responses: '200': description: Returns the billing meter object. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: active aggregation: sum event_name: 00000000-0000-4000-8000-000000000002 description: Description of the sample event display_name: Sample Event value: '14.48' object: billing_metric created: 1745107200 updated: 1745107200 livemode: false schema: type: object properties: id: type: string object: type: string example: billing_metric event_name: type: string description: Unique name identifying this billing metric (e.g. api_call, storage_gb) display_name: type: string description: Human-readable label shown in reports description: type: string nullable: true aggregation: type: string enum: - sum - average - count - count_unique description: How usage events are aggregated. 'count_unique' deduplicates by reference/idempotency key. value: type: string nullable: true description: Default value applied to events that don't specify their own (serialized as decimal string, e.g. '1.5') status: type: string enum: - active - inactive - pending livemode: type: boolean created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - event_name - aggregation - status - livemode - created - updated '404': description: Billing metric not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" patch: summary: Update a billing metric tags: - Billing description: |- Updates an existing billing meter's properties. Note: Changing the aggregation may affect how existing events are aggregated. operationId: updateBillingMetric x-frame-sdk: resource: billing method: updateMetering security: - BearerAuth: [] parameters: - name: id in: path required: true description: The ID of the billing meter to update. schema: type: string - name: display_name in: query required: false description: A new human-readable label for this billing meter. schema: type: string - name: description in: query required: false description: A new description of what this billing meter tracks. schema: type: string - name: value in: query required: false description: The new amount associated with this billing event. schema: type: number - name: markup_percentage in: query required: false description: A percentage markup applied for calculations. schema: type: number - name: active in: query required: false description: Pass false to deactivate the billing meter. schema: type: boolean responses: '200': description: Returns the updated billing meter object. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: active aggregation: count event_name: 00000000-0000-4000-8000-000000000002 description: Description of the sample event display_name: Updated Display Name value: '87.76' object: billing_metric created: 1745107200 updated: 1745107200 livemode: false schema: type: object properties: id: type: string object: type: string example: billing_metric event_name: type: string description: Unique name identifying this billing metric (e.g. api_call, storage_gb) display_name: type: string description: Human-readable label shown in reports description: type: string nullable: true aggregation: type: string enum: - sum - average - count - count_unique description: How usage events are aggregated. 'count_unique' deduplicates by reference/idempotency key. value: type: string nullable: true description: Default value applied to events that don't specify their own (serialized as decimal string, e.g. '1.5') status: type: string enum: - active - inactive - pending livemode: type: boolean created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - event_name - aggregation - status - livemode - created - updated '404': description: Billing metric not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/accounts/{account_id}/capabilities": get: summary: List capabilities tags: - Capabilities description: Returns all capabilities for the given account. Capabilities are permissions attached to accounts that control what verification flows frameOS runs and what payment methods an account can use. operationId: listCapabilities x-frame-sdk: resource: capabilities method: list security: - BearerAuth: [] parameters: - name: account_id in: path description: The ID of the account. required: true schema: type: string responses: '200': description: A dictionary with a `data` property containing an array of capability objects. content: application/json: example: data: - id: 00000000-0000-4000-8000-000000000001 object: capability name: card_send account_id: 00000000-0000-4000-8000-000000000002 status: pending disabled_reason: ineligible_reason: currently_due: [] errors: [] created: '2025-04-20T00:00:00Z' updated: '2025-04-20T00:00:00Z' disabled: schema: type: object properties: data: type: array items: "$ref": "#/components/schemas/Capability" '404': description: Account not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" post: summary: Request capabilities tags: - Capabilities description: |- Requests one or more capabilities for an account. Capability dependencies are resolved automatically — for example, requesting `kyc_prefill` also creates `kyc` and `phone_verification` capabilities. Requesting an already-active capability is a no-op. The endpoint returns `201` when at least one new capability was created, and `200` when all requested capabilities already existed. operationId: requestCapabilities x-frame-sdk: resource: capabilities method: request security: - BearerAuth: [] parameters: - name: account_id in: path description: The ID of the account. required: true schema: type: string responses: '201': description: Returns an array of capability objects wrapped in a `data` key, including any automatically added dependencies. content: application/json: example: - id: 00000000-0000-4000-8000-000000000001 object: capability name: card_send account_id: 00000000-0000-4000-8000-000000000002 status: pending disabled_reason: ineligible_reason: currently_due: [] errors: [] created: '2025-04-20T00:00:00Z' updated: '2025-04-20T00:00:00Z' disabled: schema: type: array items: "$ref": "#/components/schemas/Capability" '200': description: Returns an array of capability objects when all requested capabilities already existed. content: application/json: example: - id: 00000000-0000-4000-8000-000000000001 object: capability name: card_send account_id: 00000000-0000-4000-8000-000000000002 status: pending disabled_reason: ineligible_reason: currently_due: [] errors: [] created: '2025-04-20T00:00:00Z' updated: '2025-04-20T00:00:00Z' disabled: schema: type: array items: "$ref": "#/components/schemas/Capability" '422': description: Invalid capability type content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '404': description: Account not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" requestBody: content: application/json: schema: type: object properties: capabilities: type: array items: type: string enum: - kyc - phone_verification - kyc_prefill - age_verification - address_verification - card_verification - bank_account_verification - creator_shield - geo_compliance - card_send - card_receive - bank_account_send - bank_account_receive description: An array of capability names to request (e.g. `["kyc", "card_receive"]`). required: - capabilities required: true "/v1/accounts/{account_id}/capabilities/{name}": get: summary: Get capability tags: - Capabilities description: Retrieves a single capability by name for the given account. Returns the full capability object including current status, any outstanding requirements, and any errors. operationId: getCapability x-frame-sdk: resource: capabilities method: get security: - BearerAuth: [] parameters: - name: account_id in: path description: The ID of the account. required: true schema: type: string - name: name in: path description: "The name of the capability to retrieve (e.g. `kyc`).:\n * `kyc` \n * `phone_verification` \n * `kyc_prefill` \n * `age_verification` \n * `address_verification` \n * `card_verification` \n * `bank_account_verification` \n * `creator_shield` \n * `geo_compliance` \n * `card_send` \n * `card_receive` \n * `bank_account_send` \n * `bank_account_receive` \n " enum: - kyc - phone_verification - kyc_prefill - age_verification - address_verification - card_verification - bank_account_verification - creator_shield - geo_compliance - card_send - card_receive - bank_account_send - bank_account_receive required: true schema: type: string responses: '200': description: Returns the capability object. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 object: capability name: card_send account_id: 00000000-0000-4000-8000-000000000002 status: active disabled_reason: ineligible_reason: currently_due: [] errors: [] created: '2025-04-20T00:00:00Z' updated: '2025-04-20T00:00:00Z' disabled: schema: "$ref": "#/components/schemas/Capability" '404': description: Capability not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" delete: summary: Disable capability tags: - Capabilities description: |- Disables a capability for an account. If disabling the capability leaves the account with no active capabilities, the account is automatically restricted. If the capability is already disabled, the request returns `200` with no state change. operationId: disableCapability x-frame-sdk: resource: capabilities method: disable security: - BearerAuth: [] parameters: - name: account_id in: path description: The ID of the account. required: true schema: type: string - name: name in: path description: "The name of the capability to disable (e.g. `kyc`).:\n * `kyc` \n * `phone_verification` \n * `kyc_prefill` \n * `age_verification` \n * `address_verification` \n * `card_verification` \n * `bank_account_verification` \n * `creator_shield` \n * `geo_compliance` \n * `card_send` \n * `card_receive` \n * `bank_account_send` \n * `bank_account_receive` \n " enum: - kyc - phone_verification - kyc_prefill - age_verification - address_verification - card_verification - bank_account_verification - creator_shield - geo_compliance - card_send - card_receive - bank_account_send - bank_account_receive required: true schema: type: string responses: '200': description: Returns the disabled capability object. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 object: capability name: card_send account_id: 00000000-0000-4000-8000-000000000002 status: disabled disabled_reason: ineligible_reason: currently_due: [] errors: [] created: '2025-04-20T00:00:00Z' updated: '2025-04-20T00:00:00Z' disabled: '2025-04-20T00:00:00Z' schema: "$ref": "#/components/schemas/Capability" '404': description: Capability not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/charge_intents": get: summary: List charge intents tags: - Charge Intents description: |- Returns a list of ChargeIntents. The ChargeIntents are returned sorted by creation date, with the most recent ChargeIntents appearing first. A dictionary with a `data` property that contains an array of up to `limit` ChargeIntents is returned. Each entry in the array is a separate Charge Intent object. If no more ChargeIntents are available, the resulting array will be empty. operationId: getChargeIntents x-frame-sdk: resource: chargeIntents method: list deprecated: true security: - BearerAuth: [] parameters: - name: page in: query description: The page offset at which you'd like to resume fetching data. required: false schema: type: integer - name: per_page in: query description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. required: false schema: type: integer - name: search in: query description: Search query for filtering charge intents required: false schema: type: string responses: '200': description: A paginated list of Charge Intent objects content: application/json: example: meta: page: 1 url: "/v1/charge_intents" has_more: false prev: next: data: - id: 00000000-0000-4000-8000-000000000001 currency: usd client_secret: ci_00000000-0000-4000-8000-000000000001_secret_000000000000000000000001 status: pending description: authorization_mode: automatic failure_description: reference_id: object: charge_intent amount: 1000 amount_captured: 0 amount_voided: 0 created: 1745107200 livemode: false subscription: invoice: latest_charge: customer: id: 00000000-0000-4000-8000-000000000002 name: Miquel Upton email: customer@frame.com description: fugit status: active date_of_birth: phone: "+13107484186" billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} customer_id: 00000000-0000-4000-8000-000000000002 account_id: account: payment_method: id: 00000000-0000-4000-8000-000000000003 customer_id: account_id: billing: id: 00000000-0000-4000-8000-000000000004 city: Mammiehaven country: US state: CA postal_code: '87940' line_1: 4970 Raynor Ways line_2: Suite 166 livemode: false type: billing type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '11' exp_year: '30' issuer: currency: segment: type: last_four: '4242' shipping: id: 00000000-0000-4000-8000-000000000005 city: East Tillie country: US state: CA postal_code: '81074' line_1: 61461 Cremin Mount line_2: Suite 737 livemode: false type: shipping metadata: {} cart_data: - id: 00000000-0000-4000-8000-000000000006 currency: usd client_secret: ci_00000000-0000-4000-8000-000000000006_secret_000000000000000000000002 status: pending description: authorization_mode: automatic failure_description: reference_id: object: charge_intent amount: 1000 amount_captured: 0 amount_voided: 0 created: 1745107200 livemode: false subscription: invoice: latest_charge: customer: id: 00000000-0000-4000-8000-000000000002 name: Miquel Upton email: customer@frame.com description: fugit status: active date_of_birth: phone: "+13107484186" billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} customer_id: 00000000-0000-4000-8000-000000000002 account_id: account: payment_method: id: 00000000-0000-4000-8000-000000000007 customer_id: account_id: billing: id: 00000000-0000-4000-8000-000000000008 city: Port Saran country: US state: CA postal_code: '00935-5089' line_1: 45276 Mraz Knolls line_2: Suite 894 livemode: false type: billing type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '05' exp_year: '30' issuer: currency: segment: type: last_four: '4242' shipping: id: 00000000-0000-4000-8000-000000000009 city: North Fletafort country: US state: CA postal_code: 71324-2132 line_1: 478 Murray Mount line_2: Suite 965 livemode: false type: shipping metadata: {} cart_data: - id: 00000000-0000-4000-8000-000000000010 currency: usd client_secret: ci_00000000-0000-4000-8000-000000000010_secret_000000000000000000000003 status: pending description: authorization_mode: automatic failure_description: reference_id: object: charge_intent amount: 1000 amount_captured: 0 amount_voided: 0 created: 1745107200 livemode: false subscription: invoice: latest_charge: customer: id: 00000000-0000-4000-8000-000000000002 name: Miquel Upton email: customer@frame.com description: fugit status: active date_of_birth: phone: "+13107484186" billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} customer_id: 00000000-0000-4000-8000-000000000002 account_id: account: payment_method: id: 00000000-0000-4000-8000-000000000011 customer_id: account_id: billing: id: 00000000-0000-4000-8000-000000000012 city: Hesselfort country: US state: CA postal_code: 40924-3945 line_1: 389 Schamberger Stream line_2: Suite 332 livemode: false type: billing type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '06' exp_year: '30' issuer: currency: segment: type: last_four: '4242' shipping: id: 00000000-0000-4000-8000-000000000013 city: O'Reillyshire country: US state: CA postal_code: '69749' line_1: 43728 Kautzer Haven line_2: Suite 291 livemode: false type: shipping metadata: {} cart_data: schema: type: object properties: data: type: array items: "$ref": "#/components/schemas/ChargeIntent" meta: type: object properties: page: type: integer has_more: type: boolean next: type: string nullable: true prev: type: string nullable: true url: type: string '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" post: summary: Create charge intent tags: - Charge Intents description: |- Creates a Charge Intent object. After the Charge Intent is created, attach a payment method and confirm to continue the payment. When you use `confirm=true` during creation, it's equivalent to creating and confirming the Charge Intent in the same call. You can use any parameters available in the confirm API when you supply `confirm=true`. operationId: createChargeIntent x-frame-sdk: resource: chargeIntents method: create deprecated: true security: - BearerAuth: [] parameters: [] responses: '200': description: Returns the created Charge Intent object content: application/json: example: id: 00000000-0000-4000-8000-000000000001 currency: usd client_secret: ci_00000000-0000-4000-8000-000000000001_secret_000000000000000000000001 status: succeeded description: Test charge authorization_mode: automatic failure_description: reference_id: object: charge_intent amount: 2999 amount_captured: 0 amount_voided: 0 created: 1745107200 livemode: false subscription: invoice: latest_charge: id: 00000000-0000-4000-8000-000000000002 currency: usd failure_code: failure_message: failure_category: description: Test charge status: succeeded acquirer_reference_number: authorization_code: SANDBOX000001 object: charge payment_method_details: id: 00000000-0000-4000-8000-000000000003 customer_id: 00000000-0000-4000-8000-000000000004 account_id: billing: type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '02' exp_year: '30' issuer: currency: segment: type: last_four: '4242' customer: 00000000-0000-4000-8000-000000000004 account: account_id: payment_method: 00000000-0000-4000-8000-000000000003 amount: 2999 amount_captured: 0 amount_refunded: 0 created: 1745107200 updated: 1745107200 livemode: false captured: true disputed: false charge_intent: 00000000-0000-4000-8000-000000000001 refunded: false net_amount: 2855 customer: id: 00000000-0000-4000-8000-000000000004 name: Kristi Stanton DO email: customer@frame.com description: sunt status: active date_of_birth: phone: "+13107484186" billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} customer_id: 00000000-0000-4000-8000-000000000004 account_id: account: payment_method: id: 00000000-0000-4000-8000-000000000003 customer_id: 00000000-0000-4000-8000-000000000004 account_id: billing: type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '02' exp_year: '30' issuer: currency: segment: type: last_four: '4242' shipping: metadata: {} cart_data: schema: "$ref": "#/components/schemas/ChargeIntent" '422': description: Unprocessable Entity - validation errors, or code `payment_method_single_use` when reusing a consumed single-use wallet (Apple Pay / Google Pay) payment method content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" requestBody: content: application/json: schema: type: object properties: amount: type: integer description: Amount intended to be collected by this Charge Intent. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00, a zero-decimal currency). currency: type: string description: Three-letter ISO currency code, in lowercase. Must be a supported currency. customer: type: string description: ID of the Customer this Charge Intent belongs to, if one exists. Payment methods attached to other Customers cannot be used with this Charge Intent. payment_method: type: string description: ID of the payment method (a PaymentMethod, Card, or compatible Source object) to attach to this Charge Intent. description: type: string description: An arbitrary string attached to the object. Often useful for displaying to users. confirm: type: boolean description: Set to true to attempt to confirm this Charge Intent immediately. This parameter defaults to false. When creating and confirming a Charge Intent at the same time, you can also provide the parameters available in the Confirm API. receipt_email: type: string description: Email address to send the receipt to. If you specify receipt_email for a payment in live mode, you send a receipt regardless of your email settings. authorization_mode: type: string description: Controls when the funds will be captured from the customer's account. metadata: type: object description: Additional custom metadata for the charge intent additionalProperties: true required: - amount - currency "/v1/charge_intents/{id}": get: summary: Get charge intent tags: - Charge Intents description: |- Retrieves the details of a Charge Intent that has previously been created. Returns a Charge Intent if a valid identifier was provided. Can be called with a secret key, or with a publishable key for client-side checkout. The publishable-key response omits `customer`, `account`, `metadata`, and `revenue_split` (the bare `customer_id` and `account_id` are still returned). operationId: getChargeIntent x-frame-sdk: resource: chargeIntents method: get deprecated: true security: - BearerAuth: [] - PublishableKey: [] parameters: - name: id in: path description: Charge intent ID required: true schema: type: string responses: '200': description: Returns the Charge Intent object for the given ID content: application/json: example: id: 00000000-0000-4000-8000-000000000001 currency: usd client_secret: ci_00000000-0000-4000-8000-000000000001_secret_000000000000000000000001 status: pending description: authorization_mode: automatic failure_description: reference_id: object: charge_intent amount: 1000 amount_captured: 0 amount_voided: 0 created: 1745107200 livemode: false subscription: invoice: latest_charge: customer: id: 00000000-0000-4000-8000-000000000002 name: Ellena Gusikowski email: customer@frame.com description: deleniti status: active date_of_birth: phone: "+13107484186" billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} customer_id: 00000000-0000-4000-8000-000000000002 account_id: account: payment_method: id: 00000000-0000-4000-8000-000000000003 customer_id: account_id: billing: id: 00000000-0000-4000-8000-000000000004 city: Trantowstad country: US state: CA postal_code: '12074' line_1: 85265 Lang Route line_2: Suite 384 livemode: false type: billing type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '07' exp_year: '30' issuer: currency: segment: type: last_four: '4242' shipping: id: 00000000-0000-4000-8000-000000000005 city: Setsukotown country: US state: CA postal_code: '70962' line_1: 986 Zemlak Square line_2: Suite 303 livemode: false type: shipping metadata: {} cart_data: schema: "$ref": "#/components/schemas/ChargeIntent" '404': description: Charge intent not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" patch: summary: Update charge intent tags: - Charge Intents description: |- Updates properties on a Charge Intent object without confirming. Depending on which properties you update, you might need to confirm the Charge Intent again. For example, updating the `payment_method` always requires you to confirm the Charge Intent again. If you prefer to update and confirm at the same time, we recommend updating properties through the confirm API instead. operationId: updateChargeIntent x-frame-sdk: resource: chargeIntents method: update deprecated: true security: - BearerAuth: [] parameters: - name: id in: path description: Charge intent ID required: true schema: type: string responses: '200': description: Returns the updated Charge Intent object content: application/json: example: id: 00000000-0000-4000-8000-000000000001 currency: usd client_secret: ci_00000000-0000-4000-8000-000000000001_secret_000000000000000000000001 status: requires_confirmation description: authorization_mode: automatic failure_description: reference_id: object: charge_intent amount: 2999 amount_captured: 0 amount_voided: 0 created: 1745107200 livemode: false subscription: invoice: latest_charge: customer: id: 00000000-0000-4000-8000-000000000002 name: Lonny Powlowski email: customer@frame.com description: quasi status: active date_of_birth: phone: "+13107484186" billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} customer_id: 00000000-0000-4000-8000-000000000002 account_id: account: payment_method: id: 00000000-0000-4000-8000-000000000003 customer_id: account_id: billing: id: 00000000-0000-4000-8000-000000000004 city: Krystlehaven country: US state: CA postal_code: '38647' line_1: 435 Casper Route line_2: Suite 808 livemode: false type: billing type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '08' exp_year: '30' issuer: currency: segment: type: last_four: '4242' shipping: id: 00000000-0000-4000-8000-000000000005 city: North Pastyton country: US state: CA postal_code: '10801' line_1: 83431 Mohr Camp line_2: Suite 600 livemode: false type: shipping metadata: {} cart_data: schema: "$ref": "#/components/schemas/ChargeIntent" '404': description: Charge intent not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" requestBody: content: application/json: schema: type: object properties: amount: type: integer description: Amount intended to be collected by this Charge Intent. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00, a zero-decimal currency). payment_method: type: string description: ID of the payment method (a PaymentMethod, Card, or compatible Source object) to attach to this Charge Intent. customer: type: string description: ID of the Customer this Charge Intent belongs to, if one exists. Payment methods attached to other Customers cannot be used with this Charge Intent. account: type: string description: type: string description: An arbitrary string attached to the object. Often useful for displaying to users. metadata: type: object additionalProperties: true description: Set of key-value pairs that you can attach to an object. "/v1/charge_intents/{id}/confirm": post: summary: Confirm charge intent tags: - Charge Intents description: |- Confirm that your customer intends to pay with current or provided payment method. Upon confirmation, the Charge Intent will attempt to initiate a payment. Returns the resulting Charge Intent after all possible transitions are applied. operationId: confirmChargeIntent x-frame-sdk: resource: chargeIntents method: confirm deprecated: true security: - BearerAuth: [] parameters: - name: id in: path description: Charge intent ID required: true schema: type: string responses: '200': description: Returns the resulting Charge Intent after all possible transitions are applied content: application/json: example: id: 00000000-0000-4000-8000-000000000001 currency: usd client_secret: ci_00000000-0000-4000-8000-000000000001_secret_000000000000000000000001 status: succeeded description: authorization_mode: automatic failure_description: reference_id: object: charge_intent amount: 1000 amount_captured: 0 amount_voided: 0 created: 1745107200 livemode: false subscription: invoice: latest_charge: id: 00000000-0000-4000-8000-000000000002 currency: usd failure_code: failure_message: failure_category: description: status: succeeded acquirer_reference_number: authorization_code: SANDBOX000001 object: charge payment_method_details: id: 00000000-0000-4000-8000-000000000003 customer_id: account_id: billing: id: 00000000-0000-4000-8000-000000000004 city: Anikashire country: US state: CA postal_code: 67510-4430 line_1: 246 Henrietta Centers line_2: Apt. 402 livemode: false type: billing type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '11' exp_year: '30' issuer: currency: segment: type: last_four: '4242' customer: 00000000-0000-4000-8000-000000000005 account: account_id: payment_method: 00000000-0000-4000-8000-000000000003 amount: 1000 amount_captured: 0 amount_refunded: 0 created: 1745107200 updated: 1745107200 livemode: false captured: true disputed: false charge_intent: 00000000-0000-4000-8000-000000000001 refunded: false net_amount: 926 customer: id: 00000000-0000-4000-8000-000000000005 name: Karlyn Waters Jr. email: customer@frame.com description: quaerat status: active date_of_birth: phone: "+13107484186" billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} customer_id: 00000000-0000-4000-8000-000000000005 account_id: account: payment_method: id: 00000000-0000-4000-8000-000000000003 customer_id: account_id: billing: id: 00000000-0000-4000-8000-000000000004 city: Anikashire country: US state: CA postal_code: 67510-4430 line_1: 246 Henrietta Centers line_2: Apt. 402 livemode: false type: billing type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '11' exp_year: '30' issuer: currency: segment: type: last_four: '4242' shipping: id: 00000000-0000-4000-8000-000000000006 city: East Adam country: US state: CA postal_code: 52272-4853 line_1: 2252 Jo Road line_2: Suite 614 livemode: false type: shipping metadata: {} cart_data: schema: "$ref": "#/components/schemas/ChargeIntent" '422': description: Unprocessable Entity - validation errors, or code `payment_method_single_use` when reusing a consumed single-use wallet (Apple Pay / Google Pay) payment method content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '404': description: Charge intent not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/charge_intents/{id}/capture": post: summary: Capture charge intent tags: - Charge Intents description: |- Capture the funds of an existing uncaptured Charge Intent. Returns a Charge Intent object with `status="succeeded"` if the Charge Intent is capturable. operationId: captureChargeIntent x-frame-sdk: resource: chargeIntents method: capture deprecated: true security: - BearerAuth: [] parameters: - name: id in: path description: Charge intent ID required: true schema: type: string responses: '200': description: Returns a Charge Intent object with status="succeeded" if the Charge Intent is capturable content: application/json: example: id: 00000000-0000-4000-8000-000000000001 currency: usd client_secret: ci_00000000-0000-4000-8000-000000000001_secret_000000000000000000000001 status: succeeded description: authorization_mode: manual failure_description: reference_id: object: charge_intent amount: 1000 amount_captured: 1000 amount_voided: 0 created: 1745107200 livemode: false subscription: invoice: latest_charge: id: 00000000-0000-4000-8000-000000000002 currency: usd failure_code: failure_message: failure_category: description: status: succeeded acquirer_reference_number: authorization_code: object: charge payment_method_details: id: 00000000-0000-4000-8000-000000000003 customer_id: account_id: billing: id: 00000000-0000-4000-8000-000000000004 city: Port Benito country: US state: CA postal_code: 21042-3567 line_1: 980 Thuy Lake line_2: Apt. 483 livemode: false type: billing type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '12' exp_year: '30' issuer: currency: segment: type: last_four: '4242' customer: 00000000-0000-4000-8000-000000000005 account: account_id: payment_method: 00000000-0000-4000-8000-000000000003 amount: 1000 amount_captured: 1000 amount_refunded: 0 created: 1745107200 updated: 1745107200 livemode: false captured: true disputed: false charge_intent: 00000000-0000-4000-8000-000000000001 refunded: false net_amount: 926 customer: id: 00000000-0000-4000-8000-000000000005 name: Torrie Pfannerstill email: customer@frame.com description: autem status: active date_of_birth: phone: "+13107484186" billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} customer_id: 00000000-0000-4000-8000-000000000005 account_id: account: payment_method: id: 00000000-0000-4000-8000-000000000003 customer_id: account_id: billing: id: 00000000-0000-4000-8000-000000000004 city: Port Benito country: US state: CA postal_code: 21042-3567 line_1: 980 Thuy Lake line_2: Apt. 483 livemode: false type: billing type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '12' exp_year: '30' issuer: currency: segment: type: last_four: '4242' shipping: id: 00000000-0000-4000-8000-000000000006 city: Gregoryland country: US state: CA postal_code: '06707' line_1: 8373 Lacy Port line_2: Suite 163 livemode: false type: shipping metadata: {} cart_data: schema: "$ref": "#/components/schemas/ChargeIntent" '400': description: Bad request content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Charge intent not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" requestBody: content: application/json: schema: type: object properties: amount_captured_cents: type: integer description: The amount to capture from the Charge Intent in cents. "/v1/charge_intents/{id}/cancel": post: summary: Cancel charge intent tags: - Charge Intents description: |- You can cancel a Charge Intent object when it's in one of these statuses: `pending`, `incomplete` or `requires_capture`. After it's canceled, no additional charges are made by the Charge Intent and any operations on the Charge Intent fail with an error. Returns a Charge Intent object if the cancellation succeeds. Returns an error if the Charge Intent is already canceled or isn't in a cancelable state. operationId: cancelChargeIntent x-frame-sdk: resource: chargeIntents method: cancel deprecated: true security: - BearerAuth: [] parameters: - name: id in: path description: Charge intent ID required: true schema: type: string responses: '200': description: Returns the canceled Charge Intent object content: application/json: example: id: 00000000-0000-4000-8000-000000000001 currency: usd client_secret: ci_00000000-0000-4000-8000-000000000001_secret_000000000000000000000001 status: canceled description: authorization_mode: automatic failure_description: reference_id: object: charge_intent amount: 1000 amount_captured: 0 amount_voided: 1000 created: 1745107200 livemode: false subscription: invoice: latest_charge: customer: id: 00000000-0000-4000-8000-000000000002 name: Oliver Kling email: customer@frame.com description: necessitatibus status: active date_of_birth: phone: "+13107484186" billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} customer_id: 00000000-0000-4000-8000-000000000002 account_id: account: payment_method: id: 00000000-0000-4000-8000-000000000003 customer_id: account_id: billing: id: 00000000-0000-4000-8000-000000000004 city: New Tamela country: US state: CA postal_code: 10830-2835 line_1: 36894 Tomiko Forest line_2: Suite 890 livemode: false type: billing type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '06' exp_year: '30' issuer: currency: segment: type: last_four: '4242' shipping: id: 00000000-0000-4000-8000-000000000005 city: New Jacquiline country: US state: CA postal_code: 67912-2758 line_1: 560 Donn Hills line_2: Suite 866 livemode: false type: shipping metadata: {} cart_data: schema: "$ref": "#/components/schemas/ChargeIntent" '400': description: Bad request content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Charge intent not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/charge_intents/{id}/void_remaining": post: summary: Void remaining authorization tags: - Charge Intents description: |- Voids the remaining amount of a Charge Intent that has been partially captured. This permanently cancels the ability to capture any remaining funds from the Charge Intent. Returns a Charge Intent object with the remaining amount voided if the operation succeeds. Returns an error if the Charge Intent is not in a state that allows voiding the remaining amount. operationId: voidRemainingChargeIntent x-frame-sdk: resource: chargeIntents method: voidRemaining deprecated: true security: - BearerAuth: [] parameters: - name: id in: path description: Charge intent ID required: true schema: type: string responses: '200': description: Returns the Charge Intent object with the remaining amount voided content: application/json: example: id: 00000000-0000-4000-8000-000000000001 currency: usd client_secret: ci_00000000-0000-4000-8000-000000000001_secret_000000000000000000000001 status: canceled description: authorization_mode: manual failure_description: reference_id: object: charge_intent amount: 5000 amount_captured: 0 amount_voided: 5000 created: 1745107200 livemode: false subscription: invoice: latest_charge: id: 00000000-0000-4000-8000-000000000002 currency: usd failure_code: failure_message: failure_category: description: status: requires_capture acquirer_reference_number: authorization_code: object: charge payment_method_details: id: 00000000-0000-4000-8000-000000000003 customer_id: account_id: billing: id: 00000000-0000-4000-8000-000000000004 city: Kipberg country: US state: CA postal_code: 70626-7964 line_1: 28432 Frami Ranch line_2: Suite 279 livemode: false type: billing type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '01' exp_year: '30' issuer: currency: segment: type: last_four: '4242' customer: 00000000-0000-4000-8000-000000000005 account: account_id: payment_method: 00000000-0000-4000-8000-000000000003 amount: 5000 amount_captured: 0 amount_refunded: 0 created: 1745107200 updated: 1745107200 livemode: false captured: false disputed: false charge_intent: 00000000-0000-4000-8000-000000000001 refunded: false net_amount: 4786 customer: id: 00000000-0000-4000-8000-000000000005 name: Ms. June Jerde email: customer@frame.com description: quia status: active date_of_birth: phone: "+13107484186" billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} customer_id: 00000000-0000-4000-8000-000000000005 account_id: account: payment_method: id: 00000000-0000-4000-8000-000000000003 customer_id: account_id: billing: id: 00000000-0000-4000-8000-000000000004 city: Kipberg country: US state: CA postal_code: 70626-7964 line_1: 28432 Frami Ranch line_2: Suite 279 livemode: false type: billing type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '01' exp_year: '30' issuer: currency: segment: type: last_four: '4242' shipping: id: 00000000-0000-4000-8000-000000000006 city: Rickieborough country: US state: CA postal_code: '82868' line_1: 79784 Weissnat Village line_2: Suite 312 livemode: false type: shipping metadata: {} cart_data: schema: "$ref": "#/components/schemas/ChargeIntent" '400': description: Bad request - unable to void remaining content: application/json: schema: type: object properties: error: type: object properties: type: type: string message: type: string '404': description: Charge intent not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/charges/{id}": get: summary: Get charge tags: - Charges description: Retrieve a charge by ID operationId: getCharge x-frame-sdk: resource: charges method: get security: - BearerAuth: [] parameters: - name: id in: path description: Charge ID required: true schema: type: string responses: '200': description: Successful response content: application/json: example: id: 00000000-0000-4000-8000-000000000001 currency: usd failure_code: failure_message: failure_category: description: status: succeeded acquirer_reference_number: authorization_code: object: charge payment_method_details: id: 00000000-0000-4000-8000-000000000002 customer_id: account_id: billing: id: 00000000-0000-4000-8000-000000000003 city: Tyronebury country: US state: CA postal_code: '70896' line_1: 46131 Yundt Gateway line_2: Suite 224 livemode: false type: billing type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '04' exp_year: '30' issuer: currency: segment: type: last_four: '4242' customer: 00000000-0000-4000-8000-000000000004 account: account_id: payment_method: 00000000-0000-4000-8000-000000000002 amount: 1000 amount_captured: 0 amount_refunded: 0 created: 1745107200 updated: 1745107200 livemode: false captured: true disputed: false charge_intent: 00000000-0000-4000-8000-000000000005 refunded: false net_amount: 926 schema: "$ref": "#/components/schemas/Charge" '404': description: Charge not found '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/charges/{id}/trace": get: summary: Get charge trace tags: - Charges description: Retrieve a charge with ledger/trace information operationId: getChargeTrace x-frame-sdk: resource: charges method: trace security: - BearerAuth: [] parameters: - name: id in: path description: Charge ID required: true schema: type: string responses: '200': description: Charge with trace data content: application/json: example: id: 00000000-0000-4000-8000-000000000001 currency: usd failure_code: failure_message: failure_category: description: status: succeeded acquirer_reference_number: authorization_code: object: charge payment_method_details: id: 00000000-0000-4000-8000-000000000002 customer_id: account_id: billing: id: 00000000-0000-4000-8000-000000000003 city: Kandacebury country: US state: CA postal_code: 15820-5335 line_1: 129 Kathleen Plain line_2: Apt. 588 livemode: false type: billing type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '05' exp_year: '30' issuer: currency: segment: type: last_four: '4242' customer: 00000000-0000-4000-8000-000000000004 account: account_id: payment_method: 00000000-0000-4000-8000-000000000002 amount: 1000 amount_captured: 0 amount_refunded: 0 created: 1745107200 updated: 1745107200 livemode: false captured: true disputed: false charge_intent: 00000000-0000-4000-8000-000000000005 refunded: false net_amount: 926 ledger: journals: [] schema: "$ref": "#/components/schemas/Charge" '404': description: Charge not found '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/coupons": get: summary: List coupons tags: - Coupons description: |- Returns a list of coupons. The coupons are returned sorted by creation date, with the most recent coupons appearing first. A dictionary with a `data` property that contains an array of coupon objects is returned. If no coupons are available, the resulting array will be empty. operationId: listCoupons x-frame-sdk: resource: coupons method: list security: - BearerAuth: [] parameters: - name: page in: query required: false description: The page offset for fetching data. schema: type: integer - name: per_page in: query required: false description: 'A limit on the number of objects to be returned. Range: 1 to 100, default is 10.' schema: type: integer - name: status in: query required: false description: "Filter coupons by status. One of `active`, `inactive`, `archived`, or `deleted`.:\n * `active` \n * `inactive` \n * `archived` \n * `deleted` \n " enum: - active - inactive - archived - deleted schema: type: string - name: discount_type in: query required: false description: Filter coupons by discount type. Either `percentage` or `fixed_amount`. enum: - percentage - fixed_amount schema: type: string - name: applicable_to in: query required: false description: Filter coupons by applicability. Either `all_products` or `specific_products`. enum: - all_products - specific_products schema: type: string responses: '200': description: A dictionary with a `data` property containing an array of coupon objects. content: application/json: example: meta: page: 1 url: "/v1/coupons?status=" has_more: false prev: next: data: - id: 00000000-0000-4000-8000-000000000001 name: SweetDeal353028 description: discount_type: percentage discount_value: '20.0' discount_value_currency: usd duration: once duration_in_months: status: active livemode: false applicable_to: all_products max_redemptions: times_redeemed: 0 minimum_order_amount_cents: 0 minimum_order_amount_currency: usd discount_cap_cents: discount_cap_currency: usd valid_from: 1745107200 valid_until: 1747699200 created: 1745107200 object: coupon is_expired: false is_maxed_out: false product_id: schema: type: object properties: data: type: array items: type: object properties: id: type: string object: type: string example: coupon name: type: string description: Unique identifier meant to be displayable (e.g. SUMMER2024) description: type: string nullable: true discount_type: type: string enum: - percentage - fixed_amount discount_value: type: string description: 0–100 for percentage; currency value for fixed_amount discount_value_currency: type: string nullable: true example: usd duration: type: string enum: - once - repeating - forever duration_in_months: type: integer nullable: true description: Required when duration is 'repeating' status: type: string enum: - active - inactive - archived - deleted applicable_to: type: string enum: - all_products - specific_products product_id: type: string nullable: true description: Present when applicable_to is 'specific_products' max_redemptions: type: integer nullable: true times_redeemed: type: integer minimum_order_amount_cents: type: integer nullable: true minimum_order_amount_currency: type: string nullable: true discount_cap_cents: type: integer nullable: true discount_cap_currency: type: string nullable: true valid_from: type: integer nullable: true description: Unix timestamp valid_until: type: integer nullable: true description: Unix timestamp is_expired: type: boolean is_maxed_out: type: boolean livemode: type: boolean created: type: integer description: Unix timestamp required: - id - object - name - discount_type - discount_value - duration - status - applicable_to - times_redeemed - livemode - created meta: "$ref": "#/components/schemas/PaginationMeta" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" post: summary: Create a coupon tags: - Coupons description: |- Creates a new coupon object. Each coupon can generate multiple customer-facing promotion codes, enabling sophisticated marketing campaigns with precise control and targeting. Returns a coupon object if the call succeeded. operationId: createCoupon x-frame-sdk: resource: coupons method: create security: - BearerAuth: [] parameters: - name: name in: query required: true description: A unique name or identifier for the coupon (e.g., "SUMMER2024"). schema: type: string - name: discount_type in: query required: true description: "The type of discount. Either `percentage` or `fixed_amount`.:\n * `percentage` \n * `fixed_amount` \n " enum: - percentage - fixed_amount schema: type: string - name: discount_value in: query required: true description: The discount amount. For percentage, use a value between 0-100 (e.g., 20 for 20%). For fixed_amount, use the currency value. schema: type: number - name: duration in: query required: true description: How long the discount applies. Either `once`, `repeating`, or `forever`. enum: - once - repeating - forever schema: type: string - name: applicable_to in: query required: true description: Which products the coupon applies to. Either `all_products` or `specific_products`. enum: - all_products - specific_products schema: type: string - name: description in: query required: false description: A brief description of the coupon's purpose. schema: type: string - name: duration_in_months in: query required: false description: Number of months the discount applies. Required when duration is `repeating`. schema: type: integer - name: status in: query required: false description: Initial status of the coupon. Either `active` or `inactive`. enum: - active - inactive schema: type: string - name: max_redemptions in: query required: false description: Maximum number of times this coupon can be redeemed. Null for unlimited. schema: type: integer - name: valid_from in: query required: false description: Date and time when the coupon becomes valid. Provide as seconds since the Unix epoch. schema: type: integer - name: valid_until in: query required: false description: Date and time when the coupon expires. Provide as seconds since the Unix epoch. schema: type: integer responses: '200': description: Returns a coupon object if the call succeeded. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 name: SUMMER2024 description: discount_type: percentage discount_value: '20.0' discount_value_currency: usd duration: once duration_in_months: status: active livemode: false applicable_to: all_products max_redemptions: times_redeemed: 0 minimum_order_amount_cents: 0 minimum_order_amount_currency: usd discount_cap_cents: discount_cap_currency: usd valid_from: 1745107200 valid_until: 1747699200 created: 1745107200 object: coupon is_expired: false is_maxed_out: false product_id: schema: type: object properties: id: type: string object: type: string example: coupon name: type: string description: Unique identifier meant to be displayable (e.g. SUMMER2024) description: type: string nullable: true discount_type: type: string enum: - percentage - fixed_amount discount_value: type: string description: 0–100 for percentage; currency value for fixed_amount discount_value_currency: type: string nullable: true example: usd duration: type: string enum: - once - repeating - forever duration_in_months: type: integer nullable: true description: Required when duration is 'repeating' status: type: string enum: - active - inactive - archived - deleted applicable_to: type: string enum: - all_products - specific_products product_id: type: string nullable: true description: Present when applicable_to is 'specific_products' max_redemptions: type: integer nullable: true times_redeemed: type: integer minimum_order_amount_cents: type: integer nullable: true minimum_order_amount_currency: type: string nullable: true discount_cap_cents: type: integer nullable: true discount_cap_currency: type: string nullable: true valid_from: type: integer nullable: true description: Unix timestamp valid_until: type: integer nullable: true description: Unix timestamp is_expired: type: boolean is_maxed_out: type: boolean livemode: type: boolean created: type: integer description: Unix timestamp required: - id - object - name - discount_type - discount_value - duration - status - applicable_to - times_redeemed - livemode - created '400': description: Validation error content: application/json: schema: "$ref": "#/components/schemas/ValidationError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/coupons/{id}": get: summary: Retrieve a coupon tags: - Coupons description: |- Retrieves the details of an existing coupon. You need only supply the unique coupon identifier that was returned upon coupon creation. Returns a coupon object if a valid identifier was provided. operationId: getCoupon x-frame-sdk: resource: coupons method: get security: - BearerAuth: [] parameters: - name: id in: path required: true description: The unique identifier of the coupon to retrieve. schema: type: string responses: '200': description: Returns a coupon object if a valid identifier was provided. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 name: GoodCode109903 description: discount_type: percentage discount_value: '20.0' discount_value_currency: usd duration: once duration_in_months: status: active livemode: false applicable_to: all_products max_redemptions: times_redeemed: 0 minimum_order_amount_cents: 0 minimum_order_amount_currency: usd discount_cap_cents: discount_cap_currency: usd valid_from: 1745107200 valid_until: 1747699200 created: 1745107200 object: coupon is_expired: false is_maxed_out: false product_id: schema: type: object properties: id: type: string object: type: string example: coupon name: type: string description: Unique identifier meant to be displayable (e.g. SUMMER2024) description: type: string nullable: true discount_type: type: string enum: - percentage - fixed_amount discount_value: type: string description: 0–100 for percentage; currency value for fixed_amount discount_value_currency: type: string nullable: true example: usd duration: type: string enum: - once - repeating - forever duration_in_months: type: integer nullable: true description: Required when duration is 'repeating' status: type: string enum: - active - inactive - archived - deleted applicable_to: type: string enum: - all_products - specific_products product_id: type: string nullable: true description: Present when applicable_to is 'specific_products' max_redemptions: type: integer nullable: true times_redeemed: type: integer minimum_order_amount_cents: type: integer nullable: true minimum_order_amount_currency: type: string nullable: true discount_cap_cents: type: integer nullable: true discount_cap_currency: type: string nullable: true valid_from: type: integer nullable: true description: Unix timestamp valid_until: type: integer nullable: true description: Unix timestamp is_expired: type: boolean is_maxed_out: type: boolean livemode: type: boolean created: type: integer description: Unix timestamp required: - id - object - name - discount_type - discount_value - duration - status - applicable_to - times_redeemed - livemode - created '404': description: Coupon not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" patch: summary: Update a coupon tags: - Coupons description: |- Updates the specific coupon by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns the coupon object if the update succeeded. operationId: updateCoupon x-frame-sdk: resource: coupons method: update security: - BearerAuth: [] parameters: - name: id in: path required: true description: The unique identifier of the coupon to update. schema: type: string - name: description in: query required: false description: Update the coupon description. schema: type: string - name: status in: query required: false description: "Update the coupon status. Either `active` or `inactive`.:\n * `active` \n * `inactive` \n " enum: - active - inactive schema: type: string - name: max_redemptions in: query required: false description: Update the maximum number of redemptions allowed. schema: type: integer responses: '200': description: Returns the coupon object if the update succeeded. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 name: AwesomePromotion678863 description: Updated description discount_type: percentage discount_value: '20.0' discount_value_currency: usd duration: once duration_in_months: status: active livemode: false applicable_to: all_products max_redemptions: times_redeemed: 0 minimum_order_amount_cents: 0 minimum_order_amount_currency: usd discount_cap_cents: discount_cap_currency: usd valid_from: 1745107200 valid_until: 1747699200 created: 1745107200 object: coupon is_expired: false is_maxed_out: false product_id: schema: type: object properties: id: type: string object: type: string example: coupon name: type: string description: Unique identifier meant to be displayable (e.g. SUMMER2024) description: type: string nullable: true discount_type: type: string enum: - percentage - fixed_amount discount_value: type: string description: 0–100 for percentage; currency value for fixed_amount discount_value_currency: type: string nullable: true example: usd duration: type: string enum: - once - repeating - forever duration_in_months: type: integer nullable: true description: Required when duration is 'repeating' status: type: string enum: - active - inactive - archived - deleted applicable_to: type: string enum: - all_products - specific_products product_id: type: string nullable: true description: Present when applicable_to is 'specific_products' max_redemptions: type: integer nullable: true times_redeemed: type: integer minimum_order_amount_cents: type: integer nullable: true minimum_order_amount_currency: type: string nullable: true discount_cap_cents: type: integer nullable: true discount_cap_currency: type: string nullable: true valid_from: type: integer nullable: true description: Unix timestamp valid_until: type: integer nullable: true description: Unix timestamp is_expired: type: boolean is_maxed_out: type: boolean livemode: type: boolean created: type: integer description: Unix timestamp required: - id - object - name - discount_type - discount_value - duration - status - applicable_to - times_redeemed - livemode - created '404': description: Coupon not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/customer_identity_verifications": post: summary: Create an identity verification tags: - Customer Identity Verifications description: |- Initiates a new customer identity verification process by submitting the customer's information. A successful request creates a new CustomerIdentityVerification object and returns a verification_url that you can provide to your customer to complete the identity check. operationId: createCustomerIdentityVerification x-frame-sdk: resource: customerIdentityVerifications method: create security: - BearerAuth: [] parameters: - name: first_name in: query required: false description: The customer's first name. schema: type: string - name: last_name in: query required: false description: The customer's last name. schema: type: string - name: date_of_birth in: query required: false description: The customer's date of birth in YYYY-MM-DD format. schema: type: string - name: email in: query required: false description: The customer's email address. Must be a valid email format. schema: type: string - name: phone_number in: query required: false description: The customer's phone number. Must be 10-11 digits (non-numeric characters are stripped). schema: type: string - name: ssn in: query required: false description: The customer's Social Security Number in XXX-XX-XXXX or XXXXXXXXXX format. schema: type: string - name: customer_id in: query required: false description: Existing customer ID (mutually exclusive with profile fields) schema: type: string responses: '200': description: Returns a CustomerIdentityVerification object. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 created: 1745107200 updated: 1745107200 pending: 0 verified: 0 failed: 0 status: incomplete verification_url: https://app.framepayments.test/customer_identity_verifications/test-id schema: type: object properties: id: type: string status: type: string enum: - incomplete - pending - verified - failed description: 'Lifecycle status. Transitions: incomplete → pending → verified or failed.' verification_url: type: string description: Secure URL for the customer to complete the identity verification process. May expire after completion. created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp pending: type: integer description: Unix timestamp when status moved to pending (0 if not yet pending) verified: type: integer description: Unix timestamp when identity was verified (0 if not yet verified) failed: type: integer description: Unix timestamp when verification failed (0 if not yet failed) required: - id - status - verification_url - created - updated '422': description: Validation error content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/customer_identity_verifications/{id}": get: summary: Retrieve an identity verification tags: - Customer Identity Verifications description: |- Retrieves the details of an existing customer identity verification, including its current status and relevant timestamps. This endpoint allows you to check the status of a verification process at any time. operationId: getCustomerIdentityVerification x-frame-sdk: resource: customerIdentityVerifications method: get security: - BearerAuth: [] parameters: - name: id in: path required: true description: Identity verification ID schema: type: string responses: '200': description: Returns a CustomerIdentityVerification object. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 created: 1745107200 updated: 1745107200 pending: 0 verified: 0 failed: 0 status: incomplete verification_url: https://app.framepayments.test/customer_identity_verifications/test-id schema: type: object properties: id: type: string status: type: string enum: - incomplete - pending - verified - failed description: 'Lifecycle status. Transitions: incomplete → pending → verified or failed.' verification_url: type: string description: Secure URL for the customer to complete the identity verification process. May expire after completion. created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp pending: type: integer description: Unix timestamp when status moved to pending (0 if not yet pending) verified: type: integer description: Unix timestamp when identity was verified (0 if not yet verified) failed: type: integer description: Unix timestamp when verification failed (0 if not yet failed) required: - id - status - verification_url - created - updated '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/customer_identity_verifications/{id}/upload_documents": post: summary: Upload identity documents tags: - Customer Identity Verifications description: Uploads supporting documents for an identity verification (e.g. front/back of ID, selfie). Accepts multipart/form-data. operationId: uploadIdentityVerificationDocuments x-frame-sdk: resource: customerIdentityVerifications method: uploadDocuments security: - BearerAuth: [] parameters: - name: id in: path required: true description: Identity verification ID schema: type: string responses: '200': description: Documents uploaded content: application/json: example: id: 00000000-0000-4000-8000-000000000001 created: 1745107200 updated: 1745107200 pending: 0 verified: 0 failed: 0 status: incomplete verification_url: https://app.framepayments.test/customer_identity_verifications/test-id schema: type: object properties: id: type: string status: type: string enum: - incomplete - pending - verified - failed description: 'Lifecycle status. Transitions: incomplete → pending → verified or failed.' verification_url: type: string description: Secure URL for the customer to complete the identity verification process. May expire after completion. created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp pending: type: integer description: Unix timestamp when status moved to pending (0 if not yet pending) verified: type: integer description: Unix timestamp when identity was verified (0 if not yet verified) failed: type: integer description: Unix timestamp when verification failed (0 if not yet failed) required: - id - status - verification_url - created - updated '422': description: Validation error content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" requestBody: content: multipart/form-data: schema: type: file description: Front of ID document "/v1/customer_identity_verifications/{customer_id}": post: summary: Create identity verification for existing customer tags: - Customer Identity Verifications description: Creates an identity verification for an existing customer by customer ID. Equivalent to calling the create endpoint with customer_id. operationId: createCustomerIdentityVerificationFromCustomer x-frame-sdk: resource: customerIdentityVerifications method: createForCustomer security: - BearerAuth: [] parameters: - name: customer_id in: path required: true description: Customer ID schema: type: string responses: '200': description: Identity verification created content: application/json: example: id: 00000000-0000-4000-8000-000000000001 created: 1745107200 updated: 1745107200 pending: 0 verified: 0 failed: 0 status: incomplete verification_url: https://app.framepayments.test/customer_identity_verifications/test-id schema: type: object properties: id: type: string status: type: string enum: - incomplete - pending - verified - failed description: 'Lifecycle status. Transitions: incomplete → pending → verified or failed.' verification_url: type: string description: Secure URL for the customer to complete the identity verification process. May expire after completion. created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp pending: type: integer description: Unix timestamp when status moved to pending (0 if not yet pending) verified: type: integer description: Unix timestamp when identity was verified (0 if not yet verified) failed: type: integer description: Unix timestamp when verification failed (0 if not yet failed) required: - id - status - verification_url - created - updated '422': description: Customer not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/customers": get: summary: List customers tags: - Customers description: |- Returns a list of your customers. The customers are returned sorted by creation date, with the most recent customers appearing first. A dictionary with a `data` property that contains an array of up to `limit` customers. Each entry in the array is a separate Customer object. If no more customers are available, the resulting array will be empty. operationId: getCustomers x-frame-sdk: resource: customers method: list deprecated: true security: - BearerAuth: [] parameters: - name: page in: query description: The page offset at which you'd like to resume fetching data. required: false schema: type: integer - name: per_page in: query description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. required: false schema: type: integer - name: email in: query description: Filter by customer email required: false schema: type: string responses: '200': description: A paginated list of Customer objects content: application/json: example: meta: page: 1 url: "/v1/customers" has_more: false prev: next: data: - id: 00000000-0000-4000-8000-000000000001 name: Tracey Dach email: customer@frame.com description: soluta status: active date_of_birth: phone: "+13107484186" payment_methods: [] billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} - id: 00000000-0000-4000-8000-000000000002 name: Mose Nader email: customer@frame.com description: facere status: active date_of_birth: phone: "+13107484186" payment_methods: [] billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} - id: 00000000-0000-4000-8000-000000000003 name: Teresa Reilly email: customer@frame.com description: voluptatum status: active date_of_birth: phone: "+13107484186" payment_methods: [] billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} schema: type: object properties: data: type: array items: "$ref": "#/components/schemas/Customer" meta: type: object properties: page: type: integer has_more: type: boolean next: type: string nullable: true prev: type: string nullable: true url: type: string '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" post: summary: Create customer tags: - Customers description: Creates a new Customer object. Returns the Customer object after successful Customer creation. Returns an error if create parameters are invalid. operationId: createCustomer x-frame-sdk: resource: customers method: create deprecated: true security: - BearerAuth: [] parameters: [] responses: '200': description: Returns the Customer object after successful Customer creation content: application/json: example: id: 00000000-0000-4000-8000-000000000001 name: John Doe email: john.doe@example.com description: status: active date_of_birth: phone: "+1 (310) 748-4186" payment_methods: [] billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} schema: "$ref": "#/components/schemas/Customer" '400': description: Bad request - validation errors content: application/json: schema: "$ref": "#/components/schemas/Error" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" requestBody: content: application/json: schema: type: object properties: email: type: string format: email description: The customer's email address. name: type: string description: The customer's full name or business name. phone: type: string description: The customer's phone number. description: type: string description: An arbitrary string attached to the object. Often useful for displaying to users. ssn: type: string description: The customer's Social Security Number in XXX-XX-XXXX or XXXXXXXXXX format. This field never returned in API responses. date_of_birth: type: string description: The customer's date of birth in YYYY-MM-DD format. metadata: type: object description: Additional custom metadata for the customer additionalProperties: true required: - email "/v1/customers/{id}": get: summary: Get customer tags: - Customers description: Retrieves a Customer object. Returns the Customer object for a valid identifier. If it's for a deleted Customer, a subset of the customer's information is returned, including a deleted property that's set to true. operationId: getCustomer x-frame-sdk: resource: customers method: get deprecated: true security: - BearerAuth: [] parameters: - name: id in: path description: Customer ID required: true schema: type: string responses: '200': description: Returns the Customer object for a valid identifier content: application/json: example: id: 00000000-0000-4000-8000-000000000001 name: Prof. Deanna Monahan email: customer@frame.com description: commodi status: active date_of_birth: phone: "+13107484186" payment_methods: [] billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} schema: "$ref": "#/components/schemas/Customer" '404': description: Customer not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" patch: summary: Update customer tags: - Customers description: |- Updates the specified Customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged. This request accepts mostly the same arguments as the Customer creation call. Returns the Customer object if the update succeeded. Returns an error if update parameters are invalid. operationId: updateCustomer x-frame-sdk: resource: customers method: update deprecated: true security: - BearerAuth: [] parameters: - name: id in: path description: Customer ID required: true schema: type: string responses: '200': description: Returns the Customer object if the update succeeded content: application/json: example: id: 00000000-0000-4000-8000-000000000001 name: New Name email: customer@frame.com description: doloremque status: active date_of_birth: phone: "+13107484186" payment_methods: [] billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} schema: "$ref": "#/components/schemas/Customer" '404': description: Customer not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" requestBody: content: application/json: schema: type: object properties: name: type: string description: The customer's full name or business name. email: type: string format: email description: The customer's email address. phone: type: string description: The customer's phone number. description: type: string description: An arbitrary string attached to the object. Often useful for displaying to users. ssn: type: string description: The customer's Social Security Number in XXX-XX-XXXX or XXXXXXXXXX format. This field is never returned in API responses. Cannot be removed once set. date_of_birth: type: string description: The customer's date of birth in YYYY-MM-DD format. Cannot be removed once set. metadata: type: object additionalProperties: true delete: summary: Delete customer tags: - Customers description: |- Permanently deletes a customer. It cannot be undone. Also immediately cancels any active subscriptions on the customer. Returns an object with a deleted parameter on success. If the Customer ID does not exist, this call returns an error. Unlike other objects, deleted customers can still be retrieved through the API in order to be able to track their history. Deleting customers removes all credit card details and prevents any further operations to be performed (such as adding a new subscription). operationId: deleteCustomer x-frame-sdk: resource: customers method: delete deprecated: true security: - BearerAuth: [] parameters: - name: id in: path description: Customer ID required: true schema: type: string responses: '200': description: Returns an object with a deleted parameter on success content: application/json: example: id: 00000000-0000-4000-8000-000000000001 object: customer deleted: true schema: type: object properties: id: type: string object: type: string example: customer deleted: type: boolean example: true '404': description: Customer not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/customers/{id}/payment_methods": get: summary: List customer payment methods tags: - Customers description: Retrieve a paginated list of payment methods for a customer operationId: getCustomerPaymentMethods x-frame-sdk: resource: customers method: getPaymentMethods deprecated: true security: - BearerAuth: [] parameters: - name: id in: path description: Customer ID required: true schema: type: string - name: page in: query description: The page offset at which you'd like to resume fetching data. required: false schema: type: integer - name: per_page in: query description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. required: false schema: type: integer responses: '200': description: A paginated list of PaymentMethod objects for the customer content: application/json: example: meta: page: 1 url: "/v1/customers/00000000-0000-4000-8000-000000000001/payment_methods" has_more: false prev: next: data: [] schema: type: object properties: data: type: array items: "$ref": "#/components/schemas/PaymentMethod" meta: "$ref": "#/components/schemas/PaginationMeta" '404': description: Customer not found '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/customers/{id}/block": post: summary: Block customer tags: - Customers description: |- Blocks an active customer, preventing all future payment activities. All payment methods associated with the Customer become `blocked`. Returns the Customer object if the block succeeded. Returns an error if block parameters are invalid. operationId: blockCustomer x-frame-sdk: resource: customers method: block deprecated: true security: - BearerAuth: [] parameters: - name: id in: path description: Customer ID required: true schema: type: string responses: '200': description: Returns the Customer object after successfully blocking the customer content: application/json: example: id: 00000000-0000-4000-8000-000000000001 name: Jane Hessel email: customer@frame.com description: libero status: blocked date_of_birth: phone: "+13107484186" payment_methods: [] billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} schema: "$ref": "#/components/schemas/Customer" '404': description: Customer not found '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/customers/{id}/unblock": post: summary: Unblock customer tags: - Customers description: |- Reactivates a blocked customer, allowing them to resume payment activities. Returns the Customer object if the unblock succeeded. Returns an error if unblock parameters are invalid. operationId: unblockCustomer x-frame-sdk: resource: customers method: unblock deprecated: true security: - BearerAuth: [] parameters: - name: id in: path description: Customer ID required: true schema: type: string responses: '200': description: Returns the Customer object after successfully unblocking the customer content: application/json: example: id: 00000000-0000-4000-8000-000000000001 name: Sherita Sporer email: customer@frame.com description: nesciunt status: active date_of_birth: phone: "+13107484186" payment_methods: [] billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} schema: "$ref": "#/components/schemas/Customer" '404': description: Customer not found '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/customers/search": get: summary: Search customers tags: - Customers description: |- Search for customers you've previously created using Frame's Search Query Language. Don't use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages. Returns a dictionary with a `data` property that contains an array of up to `limit` customers. If no objects match the query, the resulting array will be empty. operationId: searchCustomers x-frame-sdk: resource: customers method: search deprecated: true security: - BearerAuth: [] parameters: - name: q in: query description: Search query (email, name, phone) required: false schema: type: string - name: name in: query description: The customer's full name or business name. required: false schema: type: string - name: email in: query description: The customer's email address. required: false schema: type: string - name: phone in: query description: The customer's phone number. required: false schema: type: string - name: created_before in: query description: Time at which the object was created. Measured in seconds since the Unix epoch. required: false schema: type: integer - name: created_after in: query description: Time at which the object was created. Measured in seconds since the Unix epoch. required: false schema: type: integer - name: page in: query description: The page offset at which you'd like to resume fetching data. required: false schema: type: integer - name: per_page in: query description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. required: false schema: type: integer responses: '200': description: A dictionary with a data property containing an array of matching Customer objects content: application/json: example: meta: page: 1 url: "/v1/customers/search?name=John+Doe" has_more: false prev: next: data: - id: 00000000-0000-4000-8000-000000000001 name: John Doe email: john.doe@example.com description: unde status: active date_of_birth: phone: "+13107484186" payment_methods: [] billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} schema: type: object properties: data: type: array items: "$ref": "#/components/schemas/Customer" meta: type: object properties: page: type: integer has_more: type: boolean next: type: string nullable: true prev: type: string nullable: true url: type: string '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/discounts/validate": post: summary: Validate promotion codes tags: - Discounts description: Validate promotion codes for a transaction. Provide either customer_id OR account_id (mutually exclusive). Can be called with a secret key, or with a publishable key for client-side checkout (listing and retrieving discounts remain secret-key only). operationId: validateDiscounts x-frame-sdk: resource: discounts method: validate security: - BearerAuth: [] - PublishableKey: [] parameters: - name: amount_cents in: query required: true description: Transaction amount in cents schema: type: integer - name: promotion_codes in: query schema: type: array items: type: string required: true description: Array of promotion code strings - name: customer_id in: query required: false description: Customer ID (mutually exclusive with account_id) schema: type: string - name: account_id in: query required: false description: Account ID (mutually exclusive with customer_id) schema: type: string responses: '200': description: Validation successful - account owner content: application/json: example: validation_result: [] total_discount_amount_cents: 0 schema: type: object properties: validation_result: type: array items: type: object properties: code: type: string valid: type: boolean discount_amount_cents: type: integer nullable: true error: type: string nullable: true total_discount_amount_cents: type: integer '422': description: Validation error - both customer_id and account_id provided content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" "/v1/discounts": get: summary: List discounts tags: - Discounts description: Returns a paginated list of discounts for the authenticated merchant. Filter by customer_id or account_id. operationId: listDiscounts x-frame-sdk: resource: discounts method: list security: - BearerAuth: [] parameters: - name: customer_id in: query required: false description: Filter by customer ID schema: type: string - name: account_id in: query required: false description: Filter by account ID schema: type: string - name: page in: query required: false description: Page number schema: type: integer - name: per_page in: query required: false description: Results per page schema: type: integer responses: '200': description: Discounts retrieved content: application/json: example: meta: page: 1 url: "/v1/discounts" has_more: false prev: next: data: - id: 00000000-0000-4000-8000-000000000001 application_order: 1 discount_amount_cents: 1000 discount_amount_currency: usd coupon: 00000000-0000-4000-8000-000000000002 promotion_code: customer: 00000000-0000-4000-8000-000000000003 account: account_id: discountable_type: ChargeIntent object: discount created: 1745107200 updated: 1745107200 livemode: false schema: type: object properties: data: type: array items: type: object properties: id: type: string object: type: string example: discount coupon: type: string nullable: true description: ID of the coupon applied promotion_code: type: string nullable: true description: ID of the promotion code applied customer: type: string nullable: true description: ID of the customer this discount is applied to account: type: string nullable: true description: ID of the account this discount is applied to discountable_type: type: string description: The type of object this discount is applied to (e.g. ChargeIntent, Invoice) application_order: type: integer description: Order in which this discount was applied discount_amount_cents: type: integer description: Discount amount in cents discount_amount_currency: type: string example: usd livemode: type: boolean created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - discount_amount_cents - discount_amount_currency - livemode - created - updated meta: "$ref": "#/components/schemas/PaginationMeta" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/discounts/{id}": get: summary: Retrieve a discount tags: - Discounts description: Retrieves a discount by ID. operationId: getDiscount x-frame-sdk: resource: discounts method: get security: - BearerAuth: [] parameters: - name: id in: path required: true description: Discount ID schema: type: string responses: '200': description: Discount retrieved content: application/json: example: id: 00000000-0000-4000-8000-000000000001 application_order: 1 discount_amount_cents: 1000 discount_amount_currency: usd coupon: 00000000-0000-4000-8000-000000000002 promotion_code: customer: 00000000-0000-4000-8000-000000000003 account: account_id: discountable_type: ChargeIntent object: discount created: 1745107200 updated: 1745107200 livemode: false schema: type: object properties: id: type: string object: type: string example: discount coupon: type: string nullable: true description: ID of the coupon applied promotion_code: type: string nullable: true description: ID of the promotion code applied customer: type: string nullable: true description: ID of the customer this discount is applied to account: type: string nullable: true description: ID of the account this discount is applied to discountable_type: type: string description: The type of object this discount is applied to (e.g. ChargeIntent, Invoice) application_order: type: integer description: Order in which this discount was applied discount_amount_cents: type: integer description: Discount amount in cents discount_amount_currency: type: string example: usd livemode: type: boolean created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - discount_amount_cents - discount_amount_currency - livemode - created - updated '404': description: Discount not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/disputes": get: summary: List disputes tags: - Disputes description: |- Returns a list of your disputes. The disputes are returned in reverse chronological order. Use the `charge` or `charge_intent` filters to narrow results to disputes associated with a specific charge or ChargeIntent. operationId: listDisputes x-frame-sdk: resource: disputes method: list security: - BearerAuth: [] parameters: - name: page in: query required: false description: The page offset at which you'd like to resume fetching data. schema: type: integer - name: per_page in: query required: false description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. schema: type: integer - name: charge in: query required: false description: Only return disputes associated to the charge specified by this charge ID. schema: type: string - name: charge_intent in: query required: false description: Only return disputes associated to the ChargeIntent specified by this ChargeIntent ID. schema: type: string responses: '200': description: A dictionary with a data property that contains an array of up to per_page disputes. Each entry in the array is a separate Dispute object. If no other disputes are available, the resulting array is empty. content: application/json: example: meta: page: 1 url: "/v1/disputes" has_more: false prev: next: data: [] schema: type: object properties: data: type: array items: "$ref": "#/components/schemas/Dispute" meta: "$ref": "#/components/schemas/PaginationMeta" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/disputes/{id}": get: summary: Get dispute tags: - Disputes description: |- Retrieves the dispute with the given ID. Returns a dispute if a valid dispute ID was provided. Returns an error otherwise. operationId: getDispute x-frame-sdk: resource: disputes method: get security: - BearerAuth: [] parameters: - name: id in: path required: true description: The ID of the dispute to retrieve. schema: type: string responses: '200': description: Returns a dispute object if a valid dispute ID was provided. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: received amount_currency: USD amount_cents: 1000 livemode: false acquirer_reference_number: authorization_code: charge_intent: id: 00000000-0000-4000-8000-000000000002 currency: usd client_secret: ci_00000000-0000-4000-8000-000000000002_secret_000000000000000000000001 status: pending description: authorization_mode: automatic failure_description: reference_id: object: charge_intent amount: 1000 amount_captured: 0 amount_voided: 0 created: 1745107200 livemode: false subscription: invoice: latest_charge: id: 00000000-0000-4000-8000-000000000003 currency: usd failure_code: failure_message: failure_category: description: status: pending acquirer_reference_number: authorization_code: object: charge payment_method_details: id: 00000000-0000-4000-8000-000000000004 customer_id: account_id: billing: id: 00000000-0000-4000-8000-000000000005 city: South Angelika country: US state: CA postal_code: '84767' line_1: 9382 Corwin Prairie line_2: Apt. 973 livemode: false type: billing type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '07' exp_year: '30' issuer: currency: segment: type: last_four: '4242' customer: 00000000-0000-4000-8000-000000000006 account: account_id: payment_method: 00000000-0000-4000-8000-000000000004 amount: 1000 amount_captured: 0 amount_refunded: 0 created: 1745107200 updated: 1745107200 livemode: false captured: true disputed: false charge_intent: 00000000-0000-4000-8000-000000000002 refunded: false net_amount: 926 customer: id: 00000000-0000-4000-8000-000000000006 name: Marvel Denesik email: customer@frame.com description: adipisci status: active date_of_birth: phone: "+13107484186" billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} customer_id: 00000000-0000-4000-8000-000000000006 account_id: account: payment_method: id: 00000000-0000-4000-8000-000000000004 customer_id: account_id: billing: id: 00000000-0000-4000-8000-000000000005 city: South Angelika country: US state: CA postal_code: '84767' line_1: 9382 Corwin Prairie line_2: Apt. 973 livemode: false type: billing type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '07' exp_year: '30' issuer: currency: segment: type: last_four: '4242' shipping: id: 00000000-0000-4000-8000-000000000007 city: Thompsonville country: US state: CA postal_code: 12238-1036 line_1: 547 Randell Circle line_2: Suite 976 livemode: false type: shipping metadata: {} cart_data: object: dispute created: 1745107200 updated: 1745107200 display_status: under_review reason: code: description: category: schema: "$ref": "#/components/schemas/Dispute" '404': description: Not found '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" patch: summary: Update dispute tags: - Disputes description: |- Upon receiving a dispute, initiating contact with your customer is advised as the primary step. Should direct communication prove ineffective, you can opt to submit evidence through your dashboard or programmatically via the API. Different types of disputes may require specific evidence fields to increase the likelihood of a favorable resolution. Updating any field in the evidence hash submits all fields in the hash for review. operationId: updateDispute x-frame-sdk: resource: disputes method: update security: - BearerAuth: [] parameters: - name: id in: path required: true description: The ID of the dispute to update. schema: type: string responses: '200': description: Returns the updated dispute object. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: received amount_currency: USD amount_cents: 1000 livemode: false acquirer_reference_number: authorization_code: charge_intent: id: 00000000-0000-4000-8000-000000000002 currency: usd client_secret: ci_00000000-0000-4000-8000-000000000002_secret_000000000000000000000001 status: pending description: authorization_mode: automatic failure_description: reference_id: object: charge_intent amount: 1000 amount_captured: 0 amount_voided: 0 created: 1745107200 livemode: false subscription: invoice: latest_charge: id: 00000000-0000-4000-8000-000000000003 currency: usd failure_code: failure_message: failure_category: description: status: pending acquirer_reference_number: authorization_code: object: charge payment_method_details: id: 00000000-0000-4000-8000-000000000004 customer_id: account_id: billing: id: 00000000-0000-4000-8000-000000000005 city: Beattyfort country: US state: CA postal_code: '43099' line_1: 134 Halvorson Lane line_2: Suite 918 livemode: false type: billing type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '04' exp_year: '30' issuer: currency: segment: type: last_four: '4242' customer: 00000000-0000-4000-8000-000000000006 account: account_id: payment_method: 00000000-0000-4000-8000-000000000004 amount: 1000 amount_captured: 0 amount_refunded: 0 created: 1745107200 updated: 1745107200 livemode: false captured: true disputed: false charge_intent: 00000000-0000-4000-8000-000000000002 refunded: false net_amount: 926 customer: id: 00000000-0000-4000-8000-000000000006 name: Onie Nicolas email: customer@frame.com description: sed status: active date_of_birth: phone: "+13107484186" billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} customer_id: 00000000-0000-4000-8000-000000000006 account_id: account: payment_method: id: 00000000-0000-4000-8000-000000000004 customer_id: account_id: billing: id: 00000000-0000-4000-8000-000000000005 city: Beattyfort country: US state: CA postal_code: '43099' line_1: 134 Halvorson Lane line_2: Suite 918 livemode: false type: billing type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '04' exp_year: '30' issuer: currency: segment: type: last_four: '4242' shipping: id: 00000000-0000-4000-8000-000000000007 city: Marioborough country: US state: CA postal_code: 50493-8685 line_1: 800 Debby Knolls line_2: Apt. 226 livemode: false type: shipping metadata: {} cart_data: object: dispute created: 1745107200 updated: 1745107200 display_status: under_review reason: code: description: category: schema: "$ref": "#/components/schemas/Dispute" '404': description: Not found '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" requestBody: content: application/json: schema: type: object properties: shipping_carrier: type: string shipping_date: type: string format: date_time shipping_tracking_number: type: string description: The tracking number for a physical product, obtained from the delivery service. If multiple tracking numbers were generated for this purchase, please separate them with commas. customer_purchase_ip_address: type: string description: The IP address that the customer used when making the purchase. support_description: type: string refund_refusal_explanation: type: string refund_policy: type: string description: Documentation demonstrating that the customer was shown your refund policy prior to purchase. access_activity_log: type: string description: Any server or activity logs showing proof that the customer accessed or downloaded the purchased digital product. This information should include IP addresses, corresponding timestamps, and any detailed recorded activity. description: Evidence provided to respond to a dispute. Updating any field in the hash submits all fields in the hash for review. "/v1/disputes/{id}/documents": post: summary: Create dispute document tags: - Disputes description: 'Upload a document as evidence for a dispute. Accepts a single PDF file up to 2MB. Document types: `shipping_documentation`, `supporting_file`, `customer_signature`, `customer_communication`.' operationId: createDisputeDocument x-frame-sdk: resource: disputes method: createDocument security: - BearerAuth: [] parameters: - name: id in: path description: Dispute ID required: true schema: type: string responses: '201': description: Document uploaded successfully and associated with the dispute. content: application/json: example: message: Document uploaded successfully document_type: supporting_file filename: evidence.pdf schema: type: object properties: message: type: string description: Human-readable confirmation message. example: Document uploaded successfully document_type: type: string description: Type of document that was uploaded. example: supporting_file filename: type: string description: Original filename of the uploaded document. example: evidence.pdf required: - message - document_type - filename '404': description: Not found '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/geofences": get: summary: List geofences tags: - Geo Compliance description: |- Returns all active geofences for your platform, including Frame's predefined platform-level geofences and any custom geofences configured for your account. Geofences define the geographic boundaries where restrictions apply. frameOS provides a set of predefined platform-level geofences for common regulatory use cases — including prohibited states for gaming and other regulated industries — which apply automatically to all accounts with the `geo_compliance` capability. Returns a `422` error if geocompliance is not enabled for your platform. operationId: listGeofences x-frame-sdk: resource: geofences method: list security: - BearerAuth: [] responses: '200': description: A dictionary with a `data` property containing an array of geofence objects content: application/json: example: data: - id: 00000000-0000-4000-8000-000000000001 object: geofence name: California description: geofence_type: polygon active: true metadata: {} locked: false geofence_rules: [] schema: type: object properties: data: type: array items: type: object properties: id: type: string description: Unique identifier for the geofence object: type: string example: geofence name: type: string description: Display name for the geofence description: type: string nullable: true description: Optional description geofence_type: type: string description: Shape type (circle or polygon) active: type: boolean description: Whether the geofence is active metadata: type: object description: Additional metadata locked: type: boolean description: True for template-assigned geofences (read-only), false for merchant-custom geofences geofence_rules: type: array items: type: object properties: id: type: string description: Unique identifier for the geofence rule object: type: string example: geofence_rule trigger_on: type: string description: Event that triggers this rule (enter, exit, dwell) action_type: type: string description: Action to take (block_transaction, webhook, flag_user) action_payload: type: object nullable: true description: Additional payload for the action dwell_seconds: type: integer nullable: true description: Seconds to dwell before triggering (dwell rules only) active: type: boolean description: Whether this rule is active required: - id - object - trigger_on - action_type - active description: Rules that fire when an account enters or exits this geofence required: - id - object - name - geofence_type - active - locked - geofence_rules '422': description: Geo compliance not enabled for merchant content: application/json: schema: type: object properties: error: type: object properties: type: type: string message: type: string '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/invoices/{invoice_id}/line_items": get: summary: List invoice line items tags: - Invoices description: Retrieves a list of line items for a specific invoice. Line items represent individual products or services being billed on an invoice. operationId: listInvoiceLineItems x-frame-sdk: resource: invoiceLineItems method: list security: - BearerAuth: [] parameters: - name: invoice_id in: path required: true description: Invoice ID schema: type: string responses: '200': description: A dictionary with a data property that contains an array of Line Item objects content: application/json: example: data: - id: 00000000-0000-4000-8000-000000000001 description: Invoice line item description quantity: 1 unit_amount_cents: 1000 unit_amount_currency: USD object: invoice_line_item created: 1745107200 updated: 1745107200 schema: type: object properties: data: type: array items: type: object properties: id: type: string object: type: string example: invoice_line_item description: type: string quantity: type: integer unit_amount_cents: type: integer description: Price per unit in cents unit_amount_currency: type: string example: USD created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - description - quantity - unit_amount_cents - unit_amount_currency - created - updated meta: "$ref": "#/components/schemas/PaginationMeta" '404': description: Invoice not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" post: summary: Create an invoice line item tags: - Invoices description: Creates a new line item for a specific invoice. Line items can only be added when the invoice is in draft state. operationId: createInvoiceLineItem x-frame-sdk: resource: invoiceLineItems method: create security: - BearerAuth: [] parameters: - name: invoice_id in: path required: true description: Invoice ID schema: type: string - name: product in: query required: true description: The ID of the product to be added to the invoice schema: type: string - name: quantity in: query required: true description: The quantity of the product to be added to the invoice. Must be greater than 0. schema: type: integer responses: '201': description: Returns the created Line Item object if the request was successful content: application/json: example: id: 00000000-0000-4000-8000-000000000001 description: Fantastic Leather Hat quantity: 2 unit_amount_cents: 10000 unit_amount_currency: USD object: invoice_line_item created: 1745107200 updated: 1745107200 schema: type: object properties: id: type: string object: type: string example: invoice_line_item description: type: string quantity: type: integer unit_amount_cents: type: integer description: Price per unit in cents unit_amount_currency: type: string example: USD created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - description - quantity - unit_amount_cents - unit_amount_currency - created - updated '404': description: Invoice not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/invoices/{invoice_id}/line_items/{id}": get: summary: Retrieve an invoice line item tags: - Invoices description: Retrieves the details of an existing line item. Returns a Line Item object if a valid ID was provided. operationId: getInvoiceLineItem x-frame-sdk: resource: invoiceLineItems method: get security: - BearerAuth: [] parameters: - name: invoice_id in: path required: true description: Invoice ID schema: type: string - name: id in: path required: true description: Line item ID schema: type: string responses: '200': description: Returns a Line Item object if a valid ID was provided content: application/json: example: id: 00000000-0000-4000-8000-000000000001 description: Invoice line item description quantity: 1 unit_amount_cents: 1000 unit_amount_currency: USD object: invoice_line_item created: 1745107200 updated: 1745107200 schema: type: object properties: id: type: string object: type: string example: invoice_line_item description: type: string quantity: type: integer unit_amount_cents: type: integer description: Price per unit in cents unit_amount_currency: type: string example: USD created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - description - quantity - unit_amount_cents - unit_amount_currency - created - updated '404': description: Line item not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" patch: summary: Update an invoice line item tags: - Invoices description: Updates an existing line item for a specific invoice. Line items can only be edited when the invoice is in draft state. operationId: updateInvoiceLineItem x-frame-sdk: resource: invoiceLineItems method: update security: - BearerAuth: [] parameters: - name: invoice_id in: path required: true description: Invoice ID schema: type: string - name: id in: path required: true description: Line item ID schema: type: string - name: quantity in: query required: false description: The new quantity for the line item. Must be greater than 0. schema: type: integer responses: '200': description: Returns the updated Line Item object if the request was successful content: application/json: example: id: 00000000-0000-4000-8000-000000000001 description: Invoice line item description quantity: 5 unit_amount_cents: 1000 unit_amount_currency: USD object: invoice_line_item created: 1745107200 updated: 1745107200 schema: type: object properties: id: type: string object: type: string example: invoice_line_item description: type: string quantity: type: integer unit_amount_cents: type: integer description: Price per unit in cents unit_amount_currency: type: string example: USD created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - description - quantity - unit_amount_cents - unit_amount_currency - created - updated '404': description: Line item not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" delete: summary: Delete an invoice line item tags: - Invoices description: Deletes a line item from an invoice. Line items cannot be deleted if the invoice is paid. operationId: deleteInvoiceLineItem x-frame-sdk: resource: invoiceLineItems method: delete security: - BearerAuth: [] parameters: - name: invoice_id in: path required: true description: Invoice ID schema: type: string - name: id in: path required: true description: Line item ID schema: type: string responses: '200': description: Returns a confirmation that the line item has been deleted content: application/json: example: object: invoice_line_item deleted: true schema: type: object properties: object: type: string example: invoice_line_item deleted: type: boolean example: true required: - object - deleted '404': description: Line item not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/invoices": get: summary: List invoices tags: - Invoices description: |- Retrieves a list of invoices for your merchant account, with optional filtering by customer and status. Returns a dictionary with a `data` property that contains an array of Invoice objects. If no more invoices are available, the resulting array will be empty. operationId: getInvoices x-frame-sdk: resource: invoices method: list security: - BearerAuth: [] parameters: - name: page in: query description: The page offset at which you'd like to resume fetching data. required: false schema: type: integer - name: per_page in: query description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. required: false schema: type: integer - name: customer in: query description: Filter invoices by customer ID. required: false schema: type: string - name: status in: query description: "Filter invoices by status.:\n * `draft` \n * `outstanding` \n * `due` \n * `overdue` \n * `paid` \n * `written_off` \n * `voided` \n " required: false enum: - draft - outstanding - due - overdue - paid - written_off - voided schema: type: string - name: account in: query description: Filter by account ID. required: false schema: type: string - name: subscription in: query description: Filter invoices by subscription ID. required: false schema: type: string responses: '200': description: A dictionary with a `data` property containing an array of Invoice objects. content: application/json: example: meta: page: 1 url: "/v1/invoices?status=" has_more: false prev: next: data: - id: 00000000-0000-4000-8000-000000000001 invoice_number: '3' collection_method: request_payment billing_reason: status: draft due_date: description: Invoice description memo: net_terms: 0 subscription_id: object: invoice total: 1000 currency: USD livemode: false created: 1745107200 updated: 1745107200 metadata: {} customer: id: 00000000-0000-4000-8000-000000000002 name: Ayako Heathcote email: customer@frame.com description: quo status: active date_of_birth: phone: "+13107484186" payment_methods: [] billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} line_items: [] - id: 00000000-0000-4000-8000-000000000003 invoice_number: '2' collection_method: request_payment billing_reason: status: draft due_date: description: Invoice description memo: net_terms: 0 subscription_id: object: invoice total: 1000 currency: USD livemode: false created: 1745107200 updated: 1745107200 metadata: {} customer: id: 00000000-0000-4000-8000-000000000002 name: Ayako Heathcote email: customer@frame.com description: quo status: active date_of_birth: phone: "+13107484186" payment_methods: [] billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} line_items: [] - id: 00000000-0000-4000-8000-000000000004 invoice_number: '1' collection_method: request_payment billing_reason: status: draft due_date: description: Invoice description memo: net_terms: 0 subscription_id: object: invoice total: 1000 currency: USD livemode: false created: 1745107200 updated: 1745107200 metadata: {} customer: id: 00000000-0000-4000-8000-000000000002 name: Ayako Heathcote email: customer@frame.com description: quo status: active date_of_birth: phone: "+13107484186" payment_methods: [] billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} line_items: [] schema: type: object properties: data: type: array items: "$ref": "#/components/schemas/Invoice" meta: type: object properties: page: type: integer has_more: type: boolean next: type: string nullable: true prev: type: string nullable: true url: type: string '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" post: summary: Create invoice tags: - Invoices description: |- Creates a new invoice with the specified parameters. Returns the created Invoice object if the request was successful. operationId: createInvoice x-frame-sdk: resource: invoices method: create security: - BearerAuth: [] parameters: - name: customer in: query description: The ID of the customer who will be billed. required: false schema: type: string - name: account in: query description: Account ID (mutually exclusive with customer). required: false schema: type: string - name: collection_method in: query required: true description: "The collection method for this invoice. `auto_charge` automatically charges the customer's payment method when the invoice is issued. `request_payment` sends a payment request to the customer when the invoice is issued.:\n * `auto_charge` \n * `request_payment` \n " enum: - auto_charge - request_payment schema: type: string - name: due_date in: query schema: type: string format: date description: Invoice due date. required: false - name: description in: query description: An arbitrary string attached to the invoice. Often useful for displaying to customers. required: false schema: type: string - name: currency in: query description: Three-letter ISO currency code, in lowercase. Must be a supported currency. required: false schema: type: string - name: net_terms in: query description: Number of days before the invoice is due. Default is 0 (due immediately). required: false schema: type: integer - name: memo in: query description: Internal notes for the invoice (not visible to customers). required: false schema: type: string responses: '201': description: Returns the created Invoice object. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 invoice_number: 00000001-DRAFT collection_method: request_payment billing_reason: manual status: draft due_date: description: Test invoice memo: net_terms: 0 subscription_id: object: invoice total: 0 currency: USD livemode: false created: 1745107200 updated: 1745107200 metadata: {} customer: id: 00000000-0000-4000-8000-000000000002 name: Alec Wilderman DC email: customer@frame.com description: assumenda status: active date_of_birth: phone: "+13107484186" payment_methods: [] billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} line_items: [] schema: "$ref": "#/components/schemas/Invoice" '422': description: Unprocessable Entity - validation errors content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/invoices/{id}": get: summary: Get invoice tags: - Invoices description: |- Retrieves the details of an existing invoice by ID. Returns an Invoice object if a valid ID was provided. operationId: getInvoice x-frame-sdk: resource: invoices method: get security: - BearerAuth: [] parameters: - name: id in: path description: The ID of the invoice to retrieve. required: true schema: type: string responses: '200': description: Returns the Invoice object. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 invoice_number: '1' collection_method: request_payment billing_reason: status: draft due_date: description: Invoice description memo: net_terms: 0 subscription_id: object: invoice total: 1000 currency: USD livemode: false created: 1745107200 updated: 1745107200 metadata: {} customer: id: 00000000-0000-4000-8000-000000000002 name: Loma Paucek email: customer@frame.com description: non status: active date_of_birth: phone: "+13107484186" payment_methods: [] billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} line_items: [] schema: "$ref": "#/components/schemas/Invoice" '404': description: Invoice not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" patch: summary: Update invoice tags: - Invoices description: |- Updates an existing invoice with the specified parameters. Returns the updated Invoice object if the request was successful. operationId: updateInvoice x-frame-sdk: resource: invoices method: update security: - BearerAuth: [] parameters: - name: id in: path description: The ID of the invoice to update. required: true schema: type: string - name: collection_method in: query required: false description: "The collection method for this invoice. `auto_charge` automatically charges the customer's payment method when the invoice is issued. `request_payment` sends a payment request to the customer when the invoice is issued.:\n * `auto_charge` \n * `request_payment` \n " enum: - auto_charge - request_payment schema: type: string - name: due_date in: query schema: type: string format: date description: Invoice due date. required: false - name: description in: query description: An arbitrary string attached to the invoice. Often useful for displaying to customers. required: false schema: type: string - name: net_terms in: query description: Number of days before the invoice is due. required: false schema: type: integer - name: memo in: query description: Internal notes for the invoice (not visible to customers). required: false schema: type: string - name: auto_advance in: query description: Whether to automatically advance the invoice. required: false schema: type: boolean responses: '200': description: Returns the updated Invoice object. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 invoice_number: '1' collection_method: request_payment billing_reason: status: draft due_date: description: New description memo: net_terms: 0 subscription_id: object: invoice total: 1000 currency: USD livemode: false created: 1745107200 updated: 1745107200 metadata: {} customer: id: 00000000-0000-4000-8000-000000000002 name: Fr. Marisha Kilback email: customer@frame.com description: laboriosam status: active date_of_birth: phone: "+13107484186" payment_methods: [] billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} line_items: [] schema: "$ref": "#/components/schemas/Invoice" '404': description: Invoice not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/invoices/{id}/issue": post: summary: Issue invoice tags: - Invoices description: |- Issues a draft invoice to the customer, changing its status from draft to open. Returns the Invoice object with updated status if the request was successful. operationId: issueInvoice x-frame-sdk: resource: invoices method: issue security: - BearerAuth: [] parameters: - name: id in: path description: The ID of the draft invoice to issue. required: true schema: type: string responses: '200': description: Returns the Invoice object with updated status. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 invoice_number: '1' collection_method: request_payment billing_reason: status: due due_date: '2025-04-20T00:00:00.000Z' description: Invoice description memo: net_terms: 0 subscription_id: object: invoice total: 1000 currency: USD livemode: false created: 1745107200 updated: 1745107200 metadata: {} customer: id: 00000000-0000-4000-8000-000000000002 name: Amb. Collette Zulauf email: customer@frame.com description: at status: active date_of_birth: phone: "+13107484186" payment_methods: [] billing_address: shipping_address: object: customer created: 1745107200 updated: 1745107200 livemode: false metadata: {} line_items: [] schema: "$ref": "#/components/schemas/Invoice" '400': description: Bad request content: application/json: schema: "$ref": "#/components/schemas/AuthError" '404': description: Invoice not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/merchant_balance": get: summary: Retrieve merchant balance tags: - Merchant Balance description: Returns the current balance for the authenticated merchant, including available funds, reserved amounts, and pending payouts. operationId: getMerchantBalance security: - BearerAuth: [] responses: '200': description: Balance unavailable from external provider content: application/json: example: merchant_id: 00000000-0000-4000-8000-000000000001 currency: USD dots_balance: 50000.0 available_for_payout: 40000.0 reserved_amount: 5000.0 pending_payouts: 5000.0 last_updated_at: '2025-04-20T00:00:00Z' source: api status: UNAVAILABLE reason_code: DOTS_API_ERROR schema: type: object properties: merchant_id: type: string description: Merchant ID currency: type: string example: USD dots_balance: type: number format: float description: Current balance in dollars available_for_payout: type: number format: float description: Amount available for payout in dollars reserved_amount: type: number format: float description: Reserved amount in dollars pending_payouts: type: number format: float description: Amount held in pending payouts in dollars last_updated_at: type: string nullable: true description: ISO8601 timestamp of last balance update source: type: string description: Source of balance data (e.g. api, cache) status: type: string example: UNAVAILABLE reason_code: type: string example: DOTS_API_ERROR required: - status - reason_code description: Returned when the balance provider is unreachable '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/onboarding_sessions/bootstrap": get: summary: Bootstrap an embedded onboarding session tags: - Onboarding Sessions description: |- Bootstraps the frame-onboarding embedded Web Component from a client_secret. Pass the onb_sess_* credential as a Bearer token. Returns session metadata, ordered step list, and full account context in one call. operationId: bootstrapOnboardingSession security: - BearerAuth: [] responses: '200': description: Bootstrap payload returned content: application/json: example: id: 00000000-0000-4000-8000-000000000001 account_id: 00000000-0000-4000-8000-000000000002 client_secret: onb_sess_000000000000000000000001 return_url: object: onboarding_session expires_at: 1745109000 livemode: false steps: - phone_verification - id_verification account: id: 00000000-0000-4000-8000-000000000002 status: pending external_id: metadata: {} payout_payment_method_id: type: individual object: account terms_of_service: profile: individual: email: gil.wiza@medhurst.example ssn_last_four: name: first_name: Sherley middle_name: last_name: Mertz suffix: phone: number: country_code: address: birthdate: capabilities: [] created: 1745107200 updated: 1745107200 livemode: false schema: type: object properties: id: type: string description: Onboarding session ID object: type: string example: onboarding_session account_id: type: string description: ID of the account this session belongs to client_secret: type: string description: The client_secret used to authenticate this session return_url: type: string nullable: true description: Merchant return URL after onboarding completes expires_at: type: integer description: Unix timestamp when this session expires livemode: type: boolean steps: type: array items: type: string description: Ordered step keys scoped to this session. account: type: object description: Full account context. Shape is identical to GET /v1/accounts/:id. properties: id: type: string object: type: string example: account type: type: string enum: - individual - business status: type: string profile: type: object nullable: true capabilities: type: array items: type: object livemode: type: boolean created: type: integer updated: type: integer required: - id - object - type - status - capabilities required: - id - object - account_id - client_secret - expires_at - livemode - steps - account '401': description: Missing or invalid client_secret content: application/json: schema: "$ref": "#/components/schemas/AuthError" '410': description: Session has expired content: application/json: schema: type: object properties: error: type: object properties: type: type: string example: session_expired message: type: string "/v1/onboarding_sessions": post: summary: Create an onboarding session tags: - Onboarding Sessions description: |- Creates an onboarding session for an existing account. Returns a session object containing a URL you can redirect the account holder to in order to complete onboarding. The session URL is single-use and expires after 30 minutes for security reasons. If a session expires before the account holder completes onboarding, create a new session and redirect them again. Never share session URLs via email, SMS, or other external channels — always redirect the authenticated account holder within your application. operationId: createOnboardingSession x-frame-sdk: resource: onboardingSessions method: create security: - BearerAuth: [] parameters: [] responses: '201': description: Returns an onboarding session object containing a url to redirect the account holder to content: application/json: example: id: 00000000-0000-4000-8000-000000000001 account_id: 00000000-0000-4000-8000-000000000002 client_secret: onb_sess_000000000000000000000001 return_url: https://example.com/callback steps: - id_verification object: onboarding_session expires_at: 1745109000 livemode: false url: https://framepayments.test/onboarding?client_secret=onb_sess_000000000000000000000001 schema: type: object properties: id: type: string description: Unique identifier for the onboarding session object: type: string example: onboarding_session account_id: type: string description: ID of the account this session belongs to client_secret: type: string description: Client secret used to authenticate hosted onboarding flows. Begins with 'onb_sess_'. steps: type: array items: type: string description: 'List of UI step keys for this session. Possible values: id_verification, geo_compliance, payment_method' return_url: type: string nullable: true description: Optional URL to redirect the user to after completing the onboarding flow expires_at: type: integer description: Unix timestamp when session expires livemode: type: boolean description: Whether this session is in live mode (true) or test mode (false) required: - id - object - account_id - client_secret - steps - expires_at - livemode '422': description: Invalid step keys content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '404': description: Account not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" requestBody: content: application/json: schema: type: object properties: account_id: type: string description: The ID of the account to onboard. The account must already exist before creating a session. steps: type: array items: type: string description: 'Optional list of step keys to include. If omitted, all pending steps on the account are used. Valid keys: id_verification, geo_compliance, payment_method' return_url: type: string description: The URL Frame redirects the account holder to after they complete the onboarding flow. A redirect to this URL does not indicate that all requirements have been fulfilled — always retrieve the account to verify its status after redirect. required: - account_id required: true get: summary: Get onboarding session by account ID tags: - Onboarding Sessions description: |- Retrieves the onboarding session for a specific account using the account_id query parameter. Returns the session object if one exists, including the URL the account holder can be redirected to. Each account has only one active onboarding session at a time. Returns 404 if no session exists for the account or if the account is not found. A redirect to the session URL does not guarantee all requirements have been met — retrieve the account and inspect its requirements to confirm onboarding is complete. operationId: getOnboardingSessionByAccount x-frame-sdk: resource: onboardingSessions method: getByAccount security: - BearerAuth: [] parameters: - name: account_id in: query required: true description: The ID of the account to retrieve the onboarding session for. The account must already exist and belong to the authenticated merchant. schema: type: string responses: '200': description: Returns the onboarding session object for the given account content: application/json: example: id: 00000000-0000-4000-8000-000000000001 account_id: 00000000-0000-4000-8000-000000000002 client_secret: onb_sess_000000000000000000000001 return_url: steps: - id_verification object: onboarding_session expires_at: 1745109000 livemode: false url: https://framepayments.test/onboarding?client_secret=onb_sess_000000000000000000000001 schema: type: object properties: id: type: string description: Unique identifier for the onboarding session object: type: string example: onboarding_session account_id: type: string description: ID of the account this session belongs to client_secret: type: string description: Client secret used to authenticate hosted onboarding flows. Begins with 'onb_sess_'. steps: type: array items: type: string description: 'List of UI step keys for this session. Possible values: id_verification, geo_compliance, payment_method' return_url: type: string nullable: true description: Optional URL to redirect the user to after completing the onboarding flow expires_at: type: integer description: Unix timestamp when session expires livemode: type: boolean description: Whether this session is in live mode (true) or test mode (false) required: - id - object - account_id - client_secret - steps - expires_at - livemode '422': description: Missing account_id parameter content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '404': description: Onboarding session not found for account content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/payment_link_sessions": post: summary: Create payment link session tags: - Payment Link Sessions description: Create a new payment link session operationId: createPaymentLinkSession x-frame-sdk: resource: paymentLinkSessions method: create security: - BearerAuth: [] parameters: [] responses: '201': description: Payment link session created with account content: application/json: example: id: 00000000-0000-4000-8000-000000000001 customer_email: payment_status: unpaid phone_number_collection: false shipping_address_collection: false status: open client_reference_id: success_url: cancel_url: object: payment_link.session expires: 1745193600 created: 1745107200 updated: 1745107200 livemode: false customer: account: 00000000-0000-4000-8000-000000000002 payment_method: schema: type: object properties: id: type: string object: type: string example: payment_link_session link_id: type: string status: type: string payment_status: type: string success_url: type: string nullable: true cancel_url: type: string nullable: true expires_at: type: string format: date-time livemode: type: boolean '400': description: Bad request - validation error content: application/json: schema: type: object properties: type: type: string message: type: string '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" requestBody: content: application/json: schema: type: object properties: customer: type: string description: Customer ID to associate with the session (mutually exclusive with account) account: type: string description: Account ID to associate with the session (mutually exclusive with customer) customer_email: type: string format: email description: Customer email address (mutually exclusive with customer) client_reference_id: type: string description: Your internal reference ID for this session success_url: type: string format: uri description: HTTP(S) URL the payer is redirected to after a successful or processing payment, with a signed payload appended. Optional. cancel_url: type: string format: uri description: HTTP(S) URL the payer is redirected to if they cancel on the hosted checkout page, with a signed payload appended. Optional. expires_in: type: integer description: Session expiry in seconds (min 900 / 15 minutes, max 86400 / 24 hours). Defaults to 86400. phone_number_collection: type: boolean description: Whether to collect phone number during checkout shipping_address_collection: type: boolean description: Whether to collect shipping address during checkout payment_method: type: string description: Existing payment method ID to pre-fill (requires customer or account) payment_method_data: type: object description: New payment method data to pre-fill properties: type: type: string enum: - card card: type: object properties: card_number: type: string exp_month: type: string exp_year: type: string cvc: type: string required: - card_number - exp_month - exp_year - cvc required: - type line_items: type: array description: Products to include in the session (at least one required) items: type: object properties: product: type: string description: Product ID quantity_minimum: type: integer quantity_maximum: type: integer required: - product required: - line_items "/v1/payment_methods": get: summary: List payment methods tags: - Payment Methods description: |- Returns a list of PaymentMethods for Treasury flows. If you want to list the PaymentMethods attached to a Customer for payments, you should use the List a Customer's PaymentMethods API instead. A dictionary with a `data` property that contains an array of up to `limit` PaymentMethods. Each entry in the array is a separate Payment Method object. If no more PaymentMethods are available, the resulting array will be empty. operationId: getPaymentMethods x-frame-sdk: resource: paymentMethods method: list security: - BearerAuth: [] parameters: - name: page in: query description: The page offset at which you'd like to resume fetching data. required: false schema: type: integer - name: per_page in: query description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. required: false schema: type: integer responses: '200': description: A paginated list of Payment Method objects content: application/json: example: meta: page: 1 url: "/v1/payment_methods" has_more: false prev: next: data: - id: 00000000-0000-4000-8000-000000000001 customer_id: account_id: billing: type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '02' exp_year: '30' issuer: currency: segment: type: last_four: '4242' - id: 00000000-0000-4000-8000-000000000002 customer_id: account_id: billing: type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '07' exp_year: '30' issuer: currency: segment: type: last_four: '4242' - id: 00000000-0000-4000-8000-000000000003 customer_id: account_id: billing: type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '04' exp_year: '30' issuer: currency: segment: type: last_four: '4242' schema: type: object properties: data: type: array items: "$ref": "#/components/schemas/PaymentMethod" meta: type: object properties: page: type: integer has_more: type: boolean next: type: string nullable: true prev: type: string nullable: true url: type: string '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" post: summary: Create payment method tags: - Payment Methods description: |- Creates a Payment Method object. Instead of creating a Payment Method directly, we recommend using the ChargeIntents API to accept a payment immediately. A Payment Method must be bound to either a `customer` (legacy charge flow) or an `account` (frameOS charge flow) at create time, otherwise it cannot be used as a transfer source. The parameter name is `account` (not `account_id`); passing `account_id` is silently ignored. operationId: createPaymentMethod security: - BearerAuth: [] parameters: - name: type in: query enum: - card - ach description: "The type of the Payment Method. Accepted values are `card` and `ach`.:\n * `card` \n * `ach` \n " required: true schema: type: string - name: customer in: query description: The ID of the Customer to which this Payment Method is saved. Use this for the legacy ChargeIntents flow. Mutually exclusive with `account`. required: false schema: type: string - name: account in: query description: The ID of the frameOS Account to which this Payment Method is attached. Use this for the frameOS charge flow. Mutually exclusive with `customer`. required: false schema: type: string - name: card_number in: query description: The card number, as a string without any separators. Required if `type` is `card`. required: false schema: type: string - name: exp_month in: query description: Two-digit number representing the card's expiration month. Required if `type` is `card`. required: false schema: type: integer - name: exp_year in: query description: The last two-digit number representing the card's expiration year. Required if `type` is `card`. required: false schema: type: integer - name: cvc in: query description: The card's CVC. It is highly recommended to always include this value. Required if `type` is `card`. required: false schema: type: string - name: account_number in: query description: Account number of the bank account. Required if `type` is `ach`. required: false schema: type: string - name: routing_number in: query description: Routing number of the bank account. Required if `type` is `ach`. required: false schema: type: string - name: account_type in: query enum: - checking - savings description: Account type of the bank account. Required if `type` is `ach`. required: false schema: type: string responses: '200': description: Returns a Payment Method object content: application/json: example: id: 00000000-0000-4000-8000-000000000001 customer_id: 00000000-0000-4000-8000-000000000002 account_id: billing: type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '12' exp_year: '28' issuer: currency: segment: type: last_four: '4242' schema: "$ref": "#/components/schemas/PaymentMethod" '422': description: Bad request - validation errors content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/payment_methods/{id}": get: summary: Get payment method tags: - Payment Methods description: |- Retrieves a Payment Method object attached to the FrameAccount. To retrieve a payment method attached to a Customer, you should use the List a Customer's PaymentMethods API instead. Returns a Payment Method object. operationId: getPaymentMethod x-frame-sdk: resource: paymentMethods method: get security: - BearerAuth: [] parameters: - name: id in: path description: Payment method ID required: true schema: type: string responses: '200': description: Returns a Payment Method object content: application/json: example: id: 00000000-0000-4000-8000-000000000001 customer_id: account_id: billing: type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '06' exp_year: '30' issuer: currency: segment: type: last_four: '4242' schema: "$ref": "#/components/schemas/PaymentMethod" '404': description: Payment method not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" patch: summary: Update payment method tags: - Payment Methods description: |- Updates a Payment Method object. A Payment Method must be attached to a customer before it can be updated. Returns a Payment Method object. operationId: updatePaymentMethod x-frame-sdk: resource: paymentMethods method: update security: - BearerAuth: [] parameters: - name: id in: path description: Payment method ID required: true schema: type: string - name: exp_month in: query description: Two-digit number representing the card's expiration month. required: false schema: type: integer - name: exp_year in: query description: The last two-digit number representing the card's expiration year. required: false schema: type: integer responses: '200': description: Returns the updated Payment Method object content: application/json: example: id: 00000000-0000-4000-8000-000000000001 customer_id: 00000000-0000-4000-8000-000000000002 account_id: billing: type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '12' exp_year: '30' issuer: currency: segment: type: last_four: '4242' schema: "$ref": "#/components/schemas/PaymentMethod" '404': description: Payment method not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/payment_methods/{id}/attach": post: summary: Attach payment method to customer or account tags: - Payment Methods description: |- Attaches a Payment Method object to a Customer or a frameOS Account. Exactly one of `customer` or `account` must be provided. The parameter name is `account` (not `account_id`); passing `account_id` returns `Must specify either a customer or an account`. operationId: attachPaymentMethod x-frame-sdk: resource: paymentMethods method: attach security: - BearerAuth: [] parameters: - name: id in: path description: Payment method ID required: true schema: type: string - name: customer in: query description: The ID of the customer to attach the Payment Method to. Use for the legacy ChargeIntents flow. Mutually exclusive with `account`. required: false schema: type: string - name: account in: query description: The ID of the frameOS Account to attach the Payment Method to. Use for the frameOS charge flow. Mutually exclusive with `customer`. required: false schema: type: string responses: '200': description: Returns a Payment Method object content: application/json: example: id: 00000000-0000-4000-8000-000000000001 customer_id: 00000000-0000-4000-8000-000000000002 account_id: billing: type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '10' exp_year: '30' issuer: currency: segment: type: last_four: '4242' schema: "$ref": "#/components/schemas/PaymentMethod" '400': description: Bad request content: application/json: schema: type: object properties: error: type: string required: - error '404': description: Payment method not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/payment_methods/{id}/detach": post: summary: Detach payment method from customer or account tags: - Payment Methods description: |- Detaches a Payment Method object from a Customer. After a Payment Method is detached, it can no longer be used for a payment or re-attached to a Customer. Returns a Payment Method object. operationId: detachPaymentMethod x-frame-sdk: resource: paymentMethods method: detach security: - BearerAuth: [] parameters: - name: id in: path description: Payment method ID required: true schema: type: string responses: '200': description: Returns a Payment Method object with status detached content: application/json: example: id: 00000000-0000-4000-8000-000000000001 customer_id: account_id: billing: type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: detached card: brand: visa exp_month: '02' exp_year: '30' issuer: currency: segment: type: last_four: '4242' schema: "$ref": "#/components/schemas/PaymentMethod" '404': description: Payment method not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/payment_methods/{id}/block": post: summary: Block payment method tags: - Payment Methods description: |- Blocks an active payment method, preventing it from being used for future payments. Returns the payment method object if the block succeeded. Returns an error if block parameters are invalid. operationId: blockPaymentMethod x-frame-sdk: resource: paymentMethods method: block security: - BearerAuth: [] parameters: - name: id in: path description: Payment method ID required: true schema: type: string responses: '200': description: Returns the Payment Method object with status blocked content: application/json: example: id: 00000000-0000-4000-8000-000000000001 customer_id: account_id: billing: type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: blocked card: brand: visa exp_month: '01' exp_year: '30' issuer: currency: segment: type: last_four: '4242' schema: "$ref": "#/components/schemas/PaymentMethod" '404': description: Payment method not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/payment_methods/{id}/unblock": post: summary: Unblock payment method tags: - Payment Methods description: |- Reactivates a blocked payment method, allowing it to be used for future payments. Returns the payment method object if the unblock succeeded. Returns an error if unblock parameters are invalid. operationId: unblockPaymentMethod x-frame-sdk: resource: paymentMethods method: unblock security: - BearerAuth: [] parameters: - name: id in: path description: Payment method ID required: true schema: type: string responses: '200': description: Returns the Payment Method object with status active content: application/json: example: id: 00000000-0000-4000-8000-000000000001 customer_id: account_id: billing: type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '07' exp_year: '30' issuer: currency: segment: type: last_four: '4242' schema: "$ref": "#/components/schemas/PaymentMethod" '404': description: Payment method not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/payouts": post: summary: Create payout tags: - Payouts description: |- Initiate a payout to a payment method owned by an account. frameOS supports payouts to debit cards via the `card_receive` capability and to bank accounts via the `bank_account_receive` capability — each must be active on the account before funds can be disbursed. Both payout types require a verified KYC record on the account; identity verification is the foundation of payout eligibility. operationId: createPayout x-frame-sdk: resource: payouts method: create deprecated: true security: - BearerAuth: [] parameters: [] responses: '200': description: Payout object for the newly initiated disbursement content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: pending speed: asap amount: 1000 currency: USD payment_method: 00000000-0000-4000-8000-000000000002 object: payout livemode: false processor_fee: merchant_fee: customer_fee: created: 1745107200 updated: 1745107200 succeeded: failed: schema: type: object properties: id: type: string example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 object: type: string example: payout status: type: string description: Lifecycle state of the payout. One of `pending`, `approved`, `processing`, `succeeded`, or `failed`. example: pending speed: type: string nullable: true description: Payout speed selected at creation. One of `asap`, `same_day`, or `standard` for ACH payouts; `null` for card payouts. example: asap amount: type: integer description: Amount in cents. example: 1000 currency: type: string example: USD payment_method: type: string description: ID of the payment method the funds are being sent to. example: pm_abc123 livemode: type: boolean example: false processor_fee: type: integer nullable: true description: Fee charged by the payment processor, in cents. example: merchant_fee: type: integer nullable: true description: Fee charged to the merchant, in cents. example: customer_fee: type: integer nullable: true description: Fee charged to the account holder, in cents. example: created: type: integer description: Unix timestamp of when the payout was created. example: 1721010605 updated: type: integer description: Unix timestamp of when the payout was last updated. example: 1721010605 succeeded: type: integer nullable: true description: Unix timestamp of when the payout succeeded, if applicable. example: failed: type: integer nullable: true description: Unix timestamp of when the payout failed, if applicable. example: required: - id - object - status - amount - currency - payment_method - livemode - created - updated '422': description: Validation failed — amount, currency, or payment method did not pass contract checks content: application/json: schema: type: object properties: status: type: integer error: type: string code: type: string error_details: type: object '404': description: Payment method not found or does not belong to a merchant account '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" requestBody: content: application/json: schema: type: object properties: payment_method: type: string description: ID of the payment method to pay out to. Must belong to an account with the relevant payout capability active. amount: type: integer description: Amount in cents. Must be greater than 0. example: 1000 currency: type: string description: Three-letter ISO currency code. Must be `USD`. example: USD speed: type: string description: Payout speed. Required for ACH bank account payouts; must be one of `asap`, `same_day`, or `standard`. Not accepted for card (`push_to_card`) payouts. enum: - asap - same_day - standard example: asap required: - payment_method - amount - currency "/v1/products": get: summary: List products tags: - Products description: |- Returns a list of your products. The products are returned sorted by creation date, with the most recently created products appearing first. A dictionary with a `data` property that contains an array of up to `limit` products is returned. Each entry in the array is a separate product object. If no more products are available, the resulting array will be empty. operationId: getProducts x-frame-sdk: resource: products method: list security: - BearerAuth: [] parameters: - name: page in: query description: The page offset at which you'd like to resume fetching data. required: false schema: type: integer - name: per_page in: query description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. required: false schema: type: integer responses: '200': description: A paginated list of product objects content: application/json: example: meta: page: 1 url: "/v1/products" has_more: false prev: next: data: - id: 00000000-0000-4000-8000-000000000001 name: Ergonomic Copper Clock description: fugit url: https://google.com shippable: true purchase_type: one_time recurring: object: product active: true default_price: 10000 created: 1745107200 updated: 1745107200 livemode: false image: metadata: {} - id: 00000000-0000-4000-8000-000000000002 name: Enormous Wooden Table description: repellat url: https://google.com shippable: true purchase_type: one_time recurring: object: product active: true default_price: 10000 created: 1745107200 updated: 1745107200 livemode: false image: metadata: {} - id: 00000000-0000-4000-8000-000000000003 name: Fantastic Concrete Shirt description: quod url: https://google.com shippable: true purchase_type: one_time recurring: object: product active: true default_price: 10000 created: 1745107200 updated: 1745107200 livemode: false image: metadata: {} schema: type: object properties: data: type: array items: "$ref": "#/components/schemas/Product" meta: type: object properties: page: type: integer has_more: type: boolean next: type: string nullable: true prev: type: string nullable: true url: type: string '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" post: summary: Create product tags: - Products description: |- Creates a new product object. Returns a product object if the call succeeded. operationId: createProduct x-frame-sdk: resource: products method: create security: - BearerAuth: [] parameters: [] responses: '201': description: Returns a product object if the call succeeded content: application/json: example: id: 00000000-0000-4000-8000-000000000001 name: Test Product description: A test product url: shippable: false purchase_type: one_time recurring: object: product active: true default_price: 2999 created: 1745107200 updated: 1745107200 livemode: false image: metadata: {} schema: "$ref": "#/components/schemas/Product" '400': description: Bad request - validation errors content: application/json: schema: "$ref": "#/components/schemas/Error" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" requestBody: content: application/json: schema: type: object properties: name: type: string description: The product's name, meant to be displayable to the customer. description: type: string description: The product's description, meant to be displayable to the customer. Use this field to optionally store a long form explanation of the product being sold for your own rendering purposes. default_price: type: integer description: The default price for this product in cents. purchase_type: type: string enum: - one_time - recurring description: Specifies product type. Either `one_time` or `recurring`. shippable: type: boolean description: Whether this product is shipped (i.e., physical goods). url: type: string description: A URL of a publicly-accessible webpage for this product. recurring_interval: type: string enum: - daily - weekly - monthly - every_3_months - every_6_months - yearly description: Specifies billing frequency. Either `daily`, `monthly`, `weekly`, `yearly`, `every_3_months`, or `every_6_months`. Required if `purchase_type` is `recurring`. billing_credits: type: integer description: Billing credits for the product metadata: type: object description: Additional custom metadata for the product additionalProperties: true required: - name "/v1/products/{id}": get: summary: Get product tags: - Products description: |- Retrieves the details of an existing product. Supply the unique product ID from either a product creation request or the product list, and Frame will return the corresponding product information. Returns a product object if a valid identifier was provided. operationId: getProduct x-frame-sdk: resource: products method: get security: - BearerAuth: [] parameters: - name: id in: path description: Unique identifier for the product. required: true schema: type: string responses: '200': description: Returns a product object if a valid identifier was provided content: application/json: example: id: 00000000-0000-4000-8000-000000000001 name: Small Copper Coat description: provident url: https://google.com shippable: true purchase_type: one_time recurring: object: product active: true default_price: 10000 created: 1745107200 updated: 1745107200 livemode: false image: metadata: {} schema: "$ref": "#/components/schemas/Product" '404': description: Product not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" patch: summary: Update product tags: - Products description: |- Updates the specific product by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns the product object if the update succeeded. operationId: updateProduct x-frame-sdk: resource: products method: update security: - BearerAuth: [] parameters: - name: id in: path description: Unique identifier for the product. required: true schema: type: string - name: name in: query description: The product's name, meant to be displayable to the customer. required: false schema: type: string - name: description in: query description: The product's description, meant to be displayable to the customer. Use this field to optionally store a long form explanation of the product being sold for your own rendering purposes. required: false schema: type: string - name: default_price in: query description: The default price for this product in cents. required: false schema: type: integer - name: purchase_type in: query enum: - one_time - recurring description: "Specifies product type. Either `one_time` or `recurring`.:\n * `one_time` \n * `recurring` \n " required: false schema: type: string - name: shippable in: query description: Whether this product is shipped (i.e., physical goods). required: false schema: type: boolean - name: url in: query description: A URL of a publicly-accessible webpage for this product. required: false schema: type: string - name: recurring_interval in: query enum: - daily - weekly - monthly - every_3_months - every_6_months - yearly description: Specifies billing frequency. Either `daily`, `monthly`, `weekly`, `yearly`, `every_3_months`, or `every_6_months`. required: false schema: type: string - name: billing_credits in: query description: Billing credits for the product required: false schema: type: integer responses: '200': description: Returns the product object if the update succeeded content: application/json: example: id: 00000000-0000-4000-8000-000000000001 name: New Name description: quisquam url: https://google.com shippable: true purchase_type: one_time recurring: object: product active: true default_price: 10000 created: 1745107200 updated: 1745107200 livemode: false image: metadata: {} schema: "$ref": "#/components/schemas/Product" '404': description: Product not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" delete: summary: Delete product tags: - Products description: |- Delete a product. Deleting a product is only possible if it has no charges associated with it. Returns a deleted object on success. Otherwise, this call returns an error. operationId: deleteProduct x-frame-sdk: resource: products method: delete security: - BearerAuth: [] parameters: - name: id in: path description: Unique identifier for the product. required: true schema: type: string responses: '200': description: Returns a deleted object on success content: application/json: example: id: 00000000-0000-4000-8000-000000000001 object: product deleted: true schema: type: object properties: id: type: string description: Product ID object: type: string description: Object type deleted: type: boolean description: Deletion status '404': description: Product not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/products/search": get: summary: Search products tags: - Products description: |- Search for products you've previously created using Frame's Search Query Language. Don't use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages. A dictionary with a `data` property that contains an array of up to `limit` products is returned. If no objects match the query, the resulting array will be empty. operationId: searchProducts x-frame-sdk: resource: products method: search security: - BearerAuth: [] parameters: - name: name in: query description: The product's name, meant to be displayable to the customer. required: false schema: type: string - name: active in: query description: Whether the product is currently available for purchase. required: false schema: type: boolean - name: shippable in: query description: Whether this product is shipped (i.e., physical goods). required: false schema: type: boolean - name: page in: query description: The page offset at which you'd like to resume fetching data. required: false schema: type: integer - name: per_page in: query description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. required: false schema: type: integer responses: '200': description: A dictionary with a `data` property containing an array of matching product objects content: application/json: example: meta: page: 1 url: "/v1/products/search?name=iPhone" has_more: false prev: next: products: - id: 00000000-0000-4000-8000-000000000001 name: iPhone Case description: aperiam url: https://google.com shippable: true purchase_type: one_time recurring: object: product active: true default_price: 10000 created: 1745107200 updated: 1745107200 livemode: false image: metadata: {} schema: type: object properties: products: type: array items: "$ref": "#/components/schemas/Product" meta: type: object properties: page: type: integer has_more: type: boolean next: type: string nullable: true prev: type: string nullable: true url: type: string '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/promotion_codes": get: summary: List promotion codes tags: - Promotion Codes description: |- Returns a list of promotion codes. The promotion codes are returned sorted by creation date, with the most recent codes appearing first. Use the filtering parameters to narrow results by coupon, customer, active status, or first-time-transaction restriction. operationId: listPromotionCodes x-frame-sdk: resource: promotionCodes method: list security: - BearerAuth: [] parameters: - name: page in: query required: false description: The page offset for fetching data. schema: type: integer - name: per_page in: query required: false description: 'A limit on the number of objects to be returned. Range: 1 to 100, default is 10.' schema: type: integer - name: coupon_id in: query required: false description: Filter promotion codes by parent coupon ID. schema: type: string - name: customer in: query required: false description: Filter promotion codes by customer ID. schema: type: string - name: active in: query required: false description: Filter by active status (true or false). schema: type: boolean - name: first_time_transaction in: query required: false description: Filter codes restricted to first-time transactions only. schema: type: boolean responses: '200': description: A dictionary with a data property containing an array of promotion code objects, sorted by creation date descending. content: application/json: example: meta: page: 1 url: "/v1/promotion_codes" has_more: false prev: next: data: - id: 00000000-0000-4000-8000-000000000001 code: PROMO000001 active: true livemode: false first_time_transaction: false max_redemptions: 100 max_customer_redemptions: 1 times_redeemed: 0 coupon: 00000000-0000-4000-8000-000000000002 customer: minimum_amount_cents: 0 minimum_amount_currency: usd expires_at: created_at: 1745107200 object: promotion_code is_expired: false is_maxed_out: false is_redeemable: true remaining_redemptions: 100 is_customer_specific: false schema: type: object properties: data: type: array items: type: object properties: id: type: string object: type: string example: promotion_code code: type: string description: Customer-facing code, normalized to uppercase (e.g. SUMMER50) coupon: type: string description: ID of the parent coupon customer: type: string nullable: true description: ID of the customer this code is restricted to, if any active: type: boolean first_time_transaction: type: boolean description: If true, only redeemable on a customer's first transaction max_redemptions: type: integer nullable: true max_customer_redemptions: type: integer nullable: true times_redeemed: type: integer minimum_amount_cents: type: integer nullable: true minimum_amount_currency: type: string nullable: true example: usd expires_at: type: integer nullable: true description: Unix timestamp is_expired: type: boolean is_maxed_out: type: boolean is_redeemable: type: boolean description: True when active, not expired, and not maxed out remaining_redemptions: type: integer nullable: true is_customer_specific: type: boolean livemode: type: boolean created_at: type: integer description: Unix timestamp required: - id - object - code - coupon - active - first_time_transaction - times_redeemed - is_expired - is_maxed_out - is_redeemable - is_customer_specific - livemode - created_at meta: "$ref": "#/components/schemas/PaginationMeta" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" post: summary: Create a promotion code tags: - Promotion Codes description: |- Creates a new promotion code object. Promotion codes are customer-facing discount codes generated from coupon templates — while coupons define the discount structure and rules, promotion codes are the actual codes that customers enter at checkout. The code string is automatically normalized to uppercase (e.g., "summer50" becomes "SUMMER50"). Returns a promotion code object if the call succeeded. operationId: createPromotionCode x-frame-sdk: resource: promotionCodes method: create security: - BearerAuth: [] parameters: - name: code in: query required: true description: The promotion code that customers will enter at checkout. Will be automatically converted to uppercase. schema: type: string - name: coupon_id in: query required: true description: The ID of the coupon template this promotion code is based on. schema: type: string - name: active in: query required: false description: Whether this promotion code is currently active and can be used. Default is true. schema: type: boolean - name: first_time_transaction in: query required: false description: If true, this code can only be used by customers making their first purchase. Default is false. schema: type: boolean - name: max_redemptions in: query required: false description: Maximum number of times this promotion code can be redeemed. Leave null for unlimited redemptions. schema: type: integer - name: minimum_amount_cents in: query required: false description: Minimum order amount in cents required to use this promotion code (e.g., 5000 for $50.00). schema: type: integer - name: minimum_amount_currency in: query required: false description: Currency code for the minimum order amount (e.g., "USD", "EUR", "GBP"). Default is "USD". schema: type: string - name: expires_at in: query required: false description: Date and time when this promotion code expires (ISO 8601 format). Leave null for no expiration. schema: type: string - name: customer in: query required: false description: If provided, restricts this promotion code to a specific customer only. schema: type: string responses: '200': description: Returns the newly created promotion code object. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 code: WELCOME20 active: true livemode: false first_time_transaction: false max_redemptions: max_customer_redemptions: 1 times_redeemed: 0 coupon: 00000000-0000-4000-8000-000000000002 customer: minimum_amount_cents: 0 minimum_amount_currency: usd expires_at: 1747699200 created_at: 1745107200 object: promotion_code is_expired: false is_maxed_out: false is_redeemable: true remaining_redemptions: is_customer_specific: false schema: type: object properties: id: type: string object: type: string example: promotion_code code: type: string description: Customer-facing code, normalized to uppercase (e.g. SUMMER50) coupon: type: string description: ID of the parent coupon customer: type: string nullable: true description: ID of the customer this code is restricted to, if any active: type: boolean first_time_transaction: type: boolean description: If true, only redeemable on a customer's first transaction max_redemptions: type: integer nullable: true max_customer_redemptions: type: integer nullable: true times_redeemed: type: integer minimum_amount_cents: type: integer nullable: true minimum_amount_currency: type: string nullable: true example: usd expires_at: type: integer nullable: true description: Unix timestamp is_expired: type: boolean is_maxed_out: type: boolean is_redeemable: type: boolean description: True when active, not expired, and not maxed out remaining_redemptions: type: integer nullable: true is_customer_specific: type: boolean livemode: type: boolean created_at: type: integer description: Unix timestamp required: - id - object - code - coupon - active - first_time_transaction - times_redeemed - is_expired - is_maxed_out - is_redeemable - is_customer_specific - livemode - created_at '400': description: Validation error content: application/json: schema: "$ref": "#/components/schemas/ValidationError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/promotion_codes/{id}": get: summary: Retrieve a promotion code tags: - Promotion Codes description: |- Retrieves the details of an existing promotion code. You need only supply the unique promotion code identifier that was returned upon promotion code creation. Returns a promotion code object if a valid identifier was provided. operationId: getPromotionCode x-frame-sdk: resource: promotionCodes method: get security: - BearerAuth: [] parameters: - name: id in: path required: true description: The unique identifier of the promotion code to retrieve. schema: type: string responses: '200': description: Returns the promotion code object for the given ID. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 code: PROMO000001 active: true livemode: false first_time_transaction: false max_redemptions: 100 max_customer_redemptions: 1 times_redeemed: 0 coupon: 00000000-0000-4000-8000-000000000002 customer: minimum_amount_cents: 0 minimum_amount_currency: usd expires_at: created_at: 1745107200 object: promotion_code is_expired: false is_maxed_out: false is_redeemable: true remaining_redemptions: 100 is_customer_specific: false schema: type: object properties: id: type: string object: type: string example: promotion_code code: type: string description: Customer-facing code, normalized to uppercase (e.g. SUMMER50) coupon: type: string description: ID of the parent coupon customer: type: string nullable: true description: ID of the customer this code is restricted to, if any active: type: boolean first_time_transaction: type: boolean description: If true, only redeemable on a customer's first transaction max_redemptions: type: integer nullable: true max_customer_redemptions: type: integer nullable: true times_redeemed: type: integer minimum_amount_cents: type: integer nullable: true minimum_amount_currency: type: string nullable: true example: usd expires_at: type: integer nullable: true description: Unix timestamp is_expired: type: boolean is_maxed_out: type: boolean is_redeemable: type: boolean description: True when active, not expired, and not maxed out remaining_redemptions: type: integer nullable: true is_customer_specific: type: boolean livemode: type: boolean created_at: type: integer description: Unix timestamp required: - id - object - code - coupon - active - first_time_transaction - times_redeemed - is_expired - is_maxed_out - is_redeemable - is_customer_specific - livemode - created_at '404': description: Promotion code not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" patch: summary: Update a promotion code tags: - Promotion Codes description: |- Updates the specific promotion code by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns the promotion code object if the update succeeded. operationId: updatePromotionCode x-frame-sdk: resource: promotionCodes method: update security: - BearerAuth: [] parameters: - name: id in: path required: true description: The unique identifier of the promotion code to update. schema: type: string - name: code in: query required: false description: Update the promotion code. Will be automatically converted to uppercase. schema: type: string - name: active in: query required: false description: Update whether this promotion code is active and can be used. schema: type: boolean - name: customer in: query required: false description: Update or set customer restriction. Set to a customer ID to restrict usage, or null to remove restriction. schema: type: string - name: first_time_transaction in: query required: false description: Update whether this code is restricted to first-time customers only. schema: type: boolean - name: max_redemptions in: query required: false description: Update the maximum number of redemptions allowed. schema: type: integer - name: minimum_amount_cents in: query required: false description: Update the minimum order amount in cents. schema: type: integer - name: minimum_amount_currency in: query required: false description: Update the currency for minimum order amount. schema: type: string - name: expires_at in: query required: false description: Update the expiration date and time (ISO 8601 format). Set to null to remove expiration. schema: type: string responses: '200': description: Returns the updated promotion code object. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 code: PROMO000001 active: false livemode: false first_time_transaction: false max_redemptions: 100 max_customer_redemptions: 1 times_redeemed: 0 coupon: 00000000-0000-4000-8000-000000000002 customer: minimum_amount_cents: 0 minimum_amount_currency: usd expires_at: created_at: 1745107200 object: promotion_code is_expired: false is_maxed_out: false is_redeemable: false remaining_redemptions: 100 is_customer_specific: false schema: type: object properties: id: type: string object: type: string example: promotion_code code: type: string description: Customer-facing code, normalized to uppercase (e.g. SUMMER50) coupon: type: string description: ID of the parent coupon customer: type: string nullable: true description: ID of the customer this code is restricted to, if any active: type: boolean first_time_transaction: type: boolean description: If true, only redeemable on a customer's first transaction max_redemptions: type: integer nullable: true max_customer_redemptions: type: integer nullable: true times_redeemed: type: integer minimum_amount_cents: type: integer nullable: true minimum_amount_currency: type: string nullable: true example: usd expires_at: type: integer nullable: true description: Unix timestamp is_expired: type: boolean is_maxed_out: type: boolean is_redeemable: type: boolean description: True when active, not expired, and not maxed out remaining_redemptions: type: integer nullable: true is_customer_specific: type: boolean livemode: type: boolean created_at: type: integer description: Unix timestamp required: - id - object - code - coupon - active - first_time_transaction - times_redeemed - is_expired - is_maxed_out - is_redeemable - is_customer_specific - livemode - created_at '404': description: Promotion code not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/refunds": get: summary: List refunds tags: - Refunds description: Returns a list of all refunds you created. We return the refunds in sorted order, with the most recent refunds appearing first. operationId: listRefunds x-frame-sdk: resource: refunds method: list security: - BearerAuth: [] parameters: - name: charge_intent in: query required: false description: Only return refunds for the ChargeIntent specified by this ID. Mutually exclusive with `transfer`. schema: type: string - name: transfer in: query required: false description: Only return refunds for the Transfer specified by this ID. Mutually exclusive with `charge_intent`. schema: type: string - name: per_page in: query required: false description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. schema: type: integer - name: page in: query required: false description: The page offset at which you'd like to resume fetching data. schema: type: integer responses: '200': description: A dictionary with a data property that contains an array of up to per_page refunds. Each entry in the array is a separate Refund object. If no other refunds are available, the resulting array is empty. content: application/json: example: meta: page: 1 url: "/v1/refunds" has_more: false prev: next: data: [] schema: type: object properties: data: type: array items: type: object meta: "$ref": "#/components/schemas/PaginationMeta" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" post: summary: Create refund tags: - Refunds description: |- To initiate a refund, specify either a Transfer or a ChargeIntent. When using a Transfer, it must be an inbound (charge-backed) transfer. Upon creating a refund, the corresponding charge, previously executed but not yet refunded, will be reimbursed. Refunds are directed back to the original credit or debit card used for the transaction. Partial refunds are permissible, allowing for multiple partial refunds until the entire charge has been reimbursed. Once a charge has been fully refunded, it cannot be refunded again. Attempting to refund an already-refunded charge, or exceeding the remaining amount on a charge, will result in an error. operationId: createRefund x-frame-sdk: resource: refunds method: create security: - BearerAuth: [] parameters: [] responses: '201': description: Returns the Refund object if the refund succeeded. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 currency: usd status: refunded amount: 100 reason: requested_by_customer charge_intent: 00000000-0000-4000-8000-000000000002 transfer: object: refund livemode: false created: 1745107200 updated: 1745107200 schema: type: object '400': description: Bad request '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" requestBody: content: application/json: schema: type: object properties: charge_intent: type: string nullable: true description: The identifier of the ChargeIntent to refund. Mutually exclusive with `transfer`. transfer: type: string nullable: true description: The identifier of the Transfer to refund. Must be an inbound (charge-backed) transfer. Mutually exclusive with `charge_intent`. amount: type: integer description: A positive integer in the smallest currency unit representing how much of this charge to refund. Can refund only up to the remaining, unrefunded amount of the charge. reason: type: string description: String indicating the reason for the refund. If you believe the charge to be fraudulent, specifying `fraudulent` as the reason will add the associated card and email to your block lists, and will also help us improve our fraud detection algorithms. enum: - duplicate - fraudulent - requested_by_customer "/v1/refunds/{id}": get: summary: Get refund tags: - Refunds description: Retrieves the details of an existing refund. Returns a refund if you provide a valid ID. Returns an error otherwise. operationId: getRefund x-frame-sdk: resource: refunds method: get security: - BearerAuth: [] parameters: - name: id in: path required: true description: The identifier of the refund to retrieve. schema: type: string responses: '200': description: Returns a refund if you provide a valid ID. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 currency: usd status: refunded amount: 1000 reason: requested_by_customer charge_intent: 00000000-0000-4000-8000-000000000002 transfer: object: refund livemode: false created: 1745107200 updated: 1745107200 schema: type: object '404': description: Not found '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/subscriptions/{subscription_id}/change_logs": get: summary: List subscription change logs tags: - Subscriptions description: Returns a paginated list of change log entries for a subscription, ordered by most recent first. Each entry captures the full before and after state of a product change, including the proration behavior used and when the adjustment was or will be collected. operationId: listSubscriptionChangeLogs x-frame-sdk: resource: subscriptionChangeLogs method: list security: - BearerAuth: [] parameters: - name: subscription_id in: path required: true description: Subscription ID schema: type: string - name: page in: query required: false description: Page number schema: type: integer - name: per_page in: query required: false description: Results per page schema: type: integer responses: '200': description: Change logs retrieved content: application/json: example: meta: page: 1 url: "/v1/subscriptions/00000000-0000-4000-8000-000000000001/change_logs" has_more: false prev: next: subscription_id: 00000000-0000-4000-8000-000000000001 subscription_change_logs: - id: 00000000-0000-4000-8000-000000000002 proration_behavior: always_invoice previous_product: 00000000-0000-4000-8000-000000000003 new_product: 00000000-0000-4000-8000-000000000004 subscription: 00000000-0000-4000-8000-000000000001 object: subscription_change_log effective_date: 1745107200 created: 1745107200 previous_plan: 00000000-0000-4000-8000-000000000005 current_plan: 00000000-0000-4000-8000-000000000006 schema: type: object properties: subscription_change_logs: type: array items: type: object properties: id: type: string object: type: string example: subscription_change_log subscription: type: string description: ID of the subscription this change applies to previous_product: type: string nullable: true description: ID of the product before the change new_product: type: string nullable: true description: ID of the product after the change previous_plan: type: string nullable: true description: ID of the subscription plan (billing configuration) before the change current_plan: type: string nullable: true description: ID of the subscription plan after the change proration_behavior: type: string enum: - always_invoice - create_prorations - none description: "'always_invoice' — immediately generate an invoice for the prorated difference. 'create_prorations' — apply the adjustment at the next renewal cycle. 'none' — no proration, new price takes effect at next billing cycle." effective_date: type: integer description: Unix timestamp when the product change took effect created: type: integer description: Unix timestamp when this log entry was created required: - id - object - subscription - effective_date - created meta: "$ref": "#/components/schemas/PaginationMeta" '404': description: Subscription not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/products/{product_id}/phases": get: summary: List product phases tags: - Products description: Returns the ordered list of billing phases configured on a product. These define the default phase schedule for subscriptions created from this product. operationId: listProductPhases x-frame-sdk: resource: productPhases method: list security: - BearerAuth: [] parameters: - name: product_id in: path required: true description: Product ID schema: type: string responses: '200': description: Phases retrieved content: application/json: example: meta: product_id: 00000000-0000-4000-8000-000000000001 phases: - id: 00000000-0000-4000-8000-000000000002 ordinal: 1 name: pricing_type: static discount_percentage: period_count: 3 phaseable_type: Product phaseable_id: 00000000-0000-4000-8000-000000000001 started_at: amount: 5000 currency: USD object: subscription_phase created: 1745107200 updated: 1745107200 livemode: true schema: type: object properties: phases: type: array items: type: object properties: id: type: string object: type: string example: subscription_phase ordinal: type: integer description: Position in the phase sequence. Must be unique within the parent resource. name: type: string nullable: true description: Optional descriptive label (e.g. 'Free Trial', 'Introductory Discount') pricing_type: type: string enum: - static - relative description: "'static' — fixed amount in cents. 'relative' — percentage discount off the base price." amount: type: integer nullable: true description: Fixed price in cents. Required when pricing_type is 'static'. currency: type: string nullable: true example: USD discount_percentage: type: string nullable: true description: Percentage discount (0–100), serialized as decimal string (e.g. '50.0'). Required when pricing_type is 'relative'. period_count: type: integer nullable: true description: Number of billing periods this phase lasts. Null means the phase runs indefinitely — no subsequent phases can follow. phaseable_type: type: string description: The parent resource type (Product or Subscription) phaseable_id: type: string description: ID of the parent product or subscription started_at: type: integer nullable: true description: Unix timestamp when this phase became active livemode: type: boolean created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - ordinal - pricing_type - phaseable_type - phaseable_id - livemode - created - updated meta: type: object '404': description: Product not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" post: summary: Create a product phase tags: - Products description: Adds a billing phase to a product. Phases define scheduled pricing tiers for subscriptions — e.g. a free trial period followed by an introductory discount, then regular pricing. operationId: createProductPhase x-frame-sdk: resource: productPhases method: create security: - BearerAuth: [] parameters: - name: product_id in: path required: true description: Product ID schema: type: string - name: ordinal in: query required: true description: Phase position (must be unique within this product) schema: type: integer - name: pricing_type in: query required: true description: static or relative schema: type: string - name: amount_cents in: query required: false description: Fixed price in cents. Required for static pricing. schema: type: integer - name: discount_percentage in: query required: false description: Discount percentage (0–100). Required for relative pricing. schema: type: number - name: period_count in: query required: false description: Number of billing periods. Null for an indefinite phase. schema: type: integer - name: name in: query required: false description: Optional label (e.g. Free Trial) schema: type: string responses: '201': description: Phase created content: application/json: example: id: 00000000-0000-4000-8000-000000000001 ordinal: 1 name: Free Trial pricing_type: relative discount_percentage: '100.0' period_count: 1 phaseable_type: Product phaseable_id: 00000000-0000-4000-8000-000000000002 started_at: amount: currency: USD object: subscription_phase created: 1745107200 updated: 1745107200 livemode: false schema: type: object properties: id: type: string object: type: string example: subscription_phase ordinal: type: integer description: Position in the phase sequence. Must be unique within the parent resource. name: type: string nullable: true description: Optional descriptive label (e.g. 'Free Trial', 'Introductory Discount') pricing_type: type: string enum: - static - relative description: "'static' — fixed amount in cents. 'relative' — percentage discount off the base price." amount: type: integer nullable: true description: Fixed price in cents. Required when pricing_type is 'static'. currency: type: string nullable: true example: USD discount_percentage: type: string nullable: true description: Percentage discount (0–100), serialized as decimal string (e.g. '50.0'). Required when pricing_type is 'relative'. period_count: type: integer nullable: true description: Number of billing periods this phase lasts. Null means the phase runs indefinitely — no subsequent phases can follow. phaseable_type: type: string description: The parent resource type (Product or Subscription) phaseable_id: type: string description: ID of the parent product or subscription started_at: type: integer nullable: true description: Unix timestamp when this phase became active livemode: type: boolean created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - ordinal - pricing_type - phaseable_type - phaseable_id - livemode - created - updated '422': description: Validation error content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/products/{product_id}/phases/{id}": get: summary: Retrieve a product phase tags: - Products description: Retrieves a single billing phase from a product. operationId: getProductPhase x-frame-sdk: resource: productPhases method: get security: - BearerAuth: [] parameters: - name: product_id in: path required: true description: Product ID schema: type: string - name: id in: path required: true description: Phase ID schema: type: string responses: '200': description: Phase retrieved content: application/json: example: id: 00000000-0000-4000-8000-000000000001 ordinal: 1 name: pricing_type: static discount_percentage: period_count: 3 phaseable_type: Product phaseable_id: 00000000-0000-4000-8000-000000000002 started_at: amount: 5000 currency: USD object: subscription_phase created: 1745107200 updated: 1745107200 livemode: true schema: type: object properties: id: type: string object: type: string example: subscription_phase ordinal: type: integer description: Position in the phase sequence. Must be unique within the parent resource. name: type: string nullable: true description: Optional descriptive label (e.g. 'Free Trial', 'Introductory Discount') pricing_type: type: string enum: - static - relative description: "'static' — fixed amount in cents. 'relative' — percentage discount off the base price." amount: type: integer nullable: true description: Fixed price in cents. Required when pricing_type is 'static'. currency: type: string nullable: true example: USD discount_percentage: type: string nullable: true description: Percentage discount (0–100), serialized as decimal string (e.g. '50.0'). Required when pricing_type is 'relative'. period_count: type: integer nullable: true description: Number of billing periods this phase lasts. Null means the phase runs indefinitely — no subsequent phases can follow. phaseable_type: type: string description: The parent resource type (Product or Subscription) phaseable_id: type: string description: ID of the parent product or subscription started_at: type: integer nullable: true description: Unix timestamp when this phase became active livemode: type: boolean created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - ordinal - pricing_type - phaseable_type - phaseable_id - livemode - created - updated '404': description: Phase not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" patch: summary: Update a product phase tags: - Products description: Updates a billing phase on a product. operationId: updateProductPhase x-frame-sdk: resource: productPhases method: update security: - BearerAuth: [] parameters: - name: product_id in: path required: true description: Product ID schema: type: string - name: id in: path required: true description: Phase ID schema: type: string - name: name in: query required: false schema: type: string - name: period_count in: query required: false schema: type: integer - name: discount_percentage in: query required: false schema: type: number - name: amount_cents in: query required: false schema: type: integer responses: '200': description: Phase updated content: application/json: example: id: 00000000-0000-4000-8000-000000000001 ordinal: 1 name: Updated Trial pricing_type: static discount_percentage: period_count: 3 phaseable_type: Product phaseable_id: 00000000-0000-4000-8000-000000000002 started_at: amount: 5000 currency: USD object: subscription_phase created: 1745107200 updated: 1745107200 livemode: true schema: type: object properties: id: type: string object: type: string example: subscription_phase ordinal: type: integer description: Position in the phase sequence. Must be unique within the parent resource. name: type: string nullable: true description: Optional descriptive label (e.g. 'Free Trial', 'Introductory Discount') pricing_type: type: string enum: - static - relative description: "'static' — fixed amount in cents. 'relative' — percentage discount off the base price." amount: type: integer nullable: true description: Fixed price in cents. Required when pricing_type is 'static'. currency: type: string nullable: true example: USD discount_percentage: type: string nullable: true description: Percentage discount (0–100), serialized as decimal string (e.g. '50.0'). Required when pricing_type is 'relative'. period_count: type: integer nullable: true description: Number of billing periods this phase lasts. Null means the phase runs indefinitely — no subsequent phases can follow. phaseable_type: type: string description: The parent resource type (Product or Subscription) phaseable_id: type: string description: ID of the parent product or subscription started_at: type: integer nullable: true description: Unix timestamp when this phase became active livemode: type: boolean created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - ordinal - pricing_type - phaseable_type - phaseable_id - livemode - created - updated '404': description: Phase not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" delete: summary: Delete a product phase tags: - Products description: Removes a billing phase from a product. operationId: deleteProductPhase x-frame-sdk: resource: productPhases method: delete security: - BearerAuth: [] parameters: - name: product_id in: path required: true description: Product ID schema: type: string - name: id in: path required: true description: Phase ID schema: type: string responses: '204': description: Phase deleted '404': description: Phase not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/products/{product_id}/phases/bulk_update": patch: summary: Bulk update product phases tags: - Products description: Replaces the full phase schedule for a product in a single operation. Send an ordered array of phase objects; existing phases not included will be removed. operationId: bulkUpdateProductPhases x-frame-sdk: resource: productPhases method: bulkUpdate security: - BearerAuth: [] parameters: - name: product_id in: path required: true description: Product ID schema: type: string responses: '200': description: Phases updated content: application/json: example: meta: product_id: 00000000-0000-4000-8000-000000000001 updated_count: 1 phases: - id: 00000000-0000-4000-8000-000000000002 ordinal: 1 name: Free Trial pricing_type: relative discount_percentage: '100.0' period_count: 1 phaseable_type: Product phaseable_id: 00000000-0000-4000-8000-000000000001 started_at: amount: currency: USD object: subscription_phase created: 1745107200 updated: 1745107200 livemode: false schema: type: object properties: phases: type: array items: type: object properties: id: type: string object: type: string example: subscription_phase ordinal: type: integer description: Position in the phase sequence. Must be unique within the parent resource. name: type: string nullable: true description: Optional descriptive label (e.g. 'Free Trial', 'Introductory Discount') pricing_type: type: string enum: - static - relative description: "'static' — fixed amount in cents. 'relative' — percentage discount off the base price." amount: type: integer nullable: true description: Fixed price in cents. Required when pricing_type is 'static'. currency: type: string nullable: true example: USD discount_percentage: type: string nullable: true description: Percentage discount (0–100), serialized as decimal string (e.g. '50.0'). Required when pricing_type is 'relative'. period_count: type: integer nullable: true description: Number of billing periods this phase lasts. Null means the phase runs indefinitely — no subsequent phases can follow. phaseable_type: type: string description: The parent resource type (Product or Subscription) phaseable_id: type: string description: ID of the parent product or subscription started_at: type: integer nullable: true description: Unix timestamp when this phase became active livemode: type: boolean created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - ordinal - pricing_type - phaseable_type - phaseable_id - livemode - created - updated meta: type: object '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" requestBody: content: application/json: schema: type: object properties: phases: type: array items: type: object description: Ordered array of phase objects. required: - phases required: true "/v1/subscriptions/{subscription_id}/phases": get: summary: List subscription phases tags: - Subscriptions description: |- Returns a list of subscription phases for a given subscription. The phases are returned in order by their ordinal value. Returns a dictionary with a `phases` property that contains an array of Subscription Phase objects. If no phases exist, the resulting array will be empty. operationId: listSubscriptionPhases x-frame-sdk: resource: subscriptionPhases method: list security: - BearerAuth: [] parameters: - name: subscription_id in: path required: true description: Subscription ID schema: type: string responses: '200': description: A dictionary with a `phases` property containing an array of Subscription Phase objects in ordinal order content: application/json: example: meta: subscription_id: 00000000-0000-4000-8000-000000000001 phases: - id: 00000000-0000-4000-8000-000000000002 ordinal: 1 name: pricing_type: static discount_percentage: period_count: 3 phaseable_type: Subscription phaseable_id: 00000000-0000-4000-8000-000000000001 started_at: amount: 5000 currency: USD object: subscription_phase created: 1745107200 updated: 1745107200 livemode: false schema: type: object properties: phases: type: array items: type: object properties: id: type: string object: type: string example: subscription_phase ordinal: type: integer description: Position in the phase sequence. Must be unique within the parent resource. name: type: string nullable: true description: Optional descriptive label (e.g. 'Free Trial', 'Introductory Discount') pricing_type: type: string enum: - static - relative description: "'static' — fixed amount in cents. 'relative' — percentage discount off the base price." amount: type: integer nullable: true description: Fixed price in cents. Required when pricing_type is 'static'. currency: type: string nullable: true example: USD discount_percentage: type: string nullable: true description: Percentage discount (0–100), serialized as decimal string (e.g. '50.0'). Required when pricing_type is 'relative'. period_count: type: integer nullable: true description: Number of billing periods this phase lasts. Null means the phase runs indefinitely — no subsequent phases can follow. phaseable_type: type: string description: The parent resource type (Product or Subscription) phaseable_id: type: string description: ID of the parent product or subscription started_at: type: integer nullable: true description: Unix timestamp when this phase became active livemode: type: boolean created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - ordinal - pricing_type - phaseable_type - phaseable_id - livemode - created - updated meta: type: object '404': description: Subscription not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" post: summary: Create a subscription phase tags: - Subscriptions description: |- Creates a new subscription phase. Note that you cannot add phases after an infinite phase has been created. Returns the Subscription Phase object after successful creation. Returns an error if create parameters are invalid. operationId: createSubscriptionPhase x-frame-sdk: resource: subscriptionPhases method: create security: - BearerAuth: [] parameters: - name: subscription_id in: path required: true description: Subscription ID schema: type: string - name: ordinal in: query required: true description: The order position of this phase in the subscription. Must be unique within the subscription. schema: type: integer - name: pricing_type in: query required: true enum: - static - relative description: "The pricing model for this phase. Can be `static` for fixed amounts or `relative` for percentage-based discounts.:\n * `static` \n * `relative` \n " schema: type: string - name: amount_cents in: query required: false description: The amount for this phase in cents. Required when `pricing_type` is `static`. schema: type: integer - name: discount_percentage in: query required: false description: The discount percentage (0-100) to apply to the base subscription amount. Required when `pricing_type` is `relative`. schema: type: number - name: period_count in: query required: false description: The number of billing periods this phase lasts. schema: type: integer - name: name in: query required: false description: A descriptive name for this phase. schema: type: string responses: '201': description: Returns the Subscription Phase object after successful creation content: application/json: example: id: 00000000-0000-4000-8000-000000000001 ordinal: 1 name: pricing_type: relative discount_percentage: '50.0' period_count: 3 phaseable_type: Subscription phaseable_id: 00000000-0000-4000-8000-000000000002 started_at: amount: currency: USD object: subscription_phase created: 1745107200 updated: 1745107200 livemode: false schema: type: object properties: id: type: string object: type: string example: subscription_phase ordinal: type: integer description: Position in the phase sequence. Must be unique within the parent resource. name: type: string nullable: true description: Optional descriptive label (e.g. 'Free Trial', 'Introductory Discount') pricing_type: type: string enum: - static - relative description: "'static' — fixed amount in cents. 'relative' — percentage discount off the base price." amount: type: integer nullable: true description: Fixed price in cents. Required when pricing_type is 'static'. currency: type: string nullable: true example: USD discount_percentage: type: string nullable: true description: Percentage discount (0–100), serialized as decimal string (e.g. '50.0'). Required when pricing_type is 'relative'. period_count: type: integer nullable: true description: Number of billing periods this phase lasts. Null means the phase runs indefinitely — no subsequent phases can follow. phaseable_type: type: string description: The parent resource type (Product or Subscription) phaseable_id: type: string description: ID of the parent product or subscription started_at: type: integer nullable: true description: Unix timestamp when this phase became active livemode: type: boolean created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - ordinal - pricing_type - phaseable_type - phaseable_id - livemode - created - updated '422': description: Validation error content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/subscriptions/{subscription_id}/phases/{id}": get: summary: Retrieve a subscription phase tags: - Subscriptions description: |- Retrieves the details of an existing subscription phase. Returns a Subscription Phase object if a valid identifier was provided. operationId: getSubscriptionPhase x-frame-sdk: resource: subscriptionPhases method: get security: - BearerAuth: [] parameters: - name: subscription_id in: path required: true description: Subscription ID schema: type: string - name: id in: path required: true description: Phase ID schema: type: string responses: '200': description: Returns a Subscription Phase object if a valid identifier was provided content: application/json: example: id: 00000000-0000-4000-8000-000000000001 ordinal: 1 name: pricing_type: static discount_percentage: period_count: 3 phaseable_type: Subscription phaseable_id: 00000000-0000-4000-8000-000000000002 started_at: amount: 5000 currency: USD object: subscription_phase created: 1745107200 updated: 1745107200 livemode: false schema: type: object properties: id: type: string object: type: string example: subscription_phase ordinal: type: integer description: Position in the phase sequence. Must be unique within the parent resource. name: type: string nullable: true description: Optional descriptive label (e.g. 'Free Trial', 'Introductory Discount') pricing_type: type: string enum: - static - relative description: "'static' — fixed amount in cents. 'relative' — percentage discount off the base price." amount: type: integer nullable: true description: Fixed price in cents. Required when pricing_type is 'static'. currency: type: string nullable: true example: USD discount_percentage: type: string nullable: true description: Percentage discount (0–100), serialized as decimal string (e.g. '50.0'). Required when pricing_type is 'relative'. period_count: type: integer nullable: true description: Number of billing periods this phase lasts. Null means the phase runs indefinitely — no subsequent phases can follow. phaseable_type: type: string description: The parent resource type (Product or Subscription) phaseable_id: type: string description: ID of the parent product or subscription started_at: type: integer nullable: true description: Unix timestamp when this phase became active livemode: type: boolean created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - ordinal - pricing_type - phaseable_type - phaseable_id - livemode - created - updated '404': description: Phase not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" patch: summary: Update a subscription phase tags: - Subscriptions description: |- Updates the specified subscription phase by setting the values of the parameters passed. Returns the updated Subscription Phase object if the update succeeded. Returns an error if update parameters are invalid. operationId: updateSubscriptionPhase x-frame-sdk: resource: subscriptionPhases method: update security: - BearerAuth: [] parameters: - name: subscription_id in: path required: true description: Subscription ID schema: type: string - name: id in: path required: true description: Phase ID schema: type: string - name: name in: query required: false description: A descriptive name for this phase. schema: type: string - name: period_count in: query required: false description: The number of billing periods this phase lasts. schema: type: integer - name: discount_percentage in: query required: false description: The discount percentage (0-100) to apply to the base subscription amount. schema: type: number - name: amount_cents in: query required: false description: The amount for this phase in cents. schema: type: integer responses: '200': description: Returns the updated Subscription Phase object content: application/json: example: id: 00000000-0000-4000-8000-000000000001 ordinal: 1 name: pricing_type: static discount_percentage: period_count: 6 phaseable_type: Subscription phaseable_id: 00000000-0000-4000-8000-000000000002 started_at: amount: 5000 currency: USD object: subscription_phase created: 1745107200 updated: 1745107200 livemode: false schema: type: object properties: id: type: string object: type: string example: subscription_phase ordinal: type: integer description: Position in the phase sequence. Must be unique within the parent resource. name: type: string nullable: true description: Optional descriptive label (e.g. 'Free Trial', 'Introductory Discount') pricing_type: type: string enum: - static - relative description: "'static' — fixed amount in cents. 'relative' — percentage discount off the base price." amount: type: integer nullable: true description: Fixed price in cents. Required when pricing_type is 'static'. currency: type: string nullable: true example: USD discount_percentage: type: string nullable: true description: Percentage discount (0–100), serialized as decimal string (e.g. '50.0'). Required when pricing_type is 'relative'. period_count: type: integer nullable: true description: Number of billing periods this phase lasts. Null means the phase runs indefinitely — no subsequent phases can follow. phaseable_type: type: string description: The parent resource type (Product or Subscription) phaseable_id: type: string description: ID of the parent product or subscription started_at: type: integer nullable: true description: Unix timestamp when this phase became active livemode: type: boolean created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - ordinal - pricing_type - phaseable_type - phaseable_id - livemode - created - updated '404': description: Phase not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" delete: summary: Delete a subscription phase tags: - Subscriptions description: |- Permanently deletes a subscription phase. This action cannot be undone. Returns an empty response with HTTP status 204 (No Content) on successful deletion. operationId: deleteSubscriptionPhase x-frame-sdk: resource: subscriptionPhases method: delete security: - BearerAuth: [] parameters: - name: subscription_id in: path required: true description: Subscription ID schema: type: string - name: id in: path required: true description: Phase ID schema: type: string responses: '204': description: Phase deleted '404': description: Phase not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/subscriptions/{subscription_id}/phases/bulk_update": patch: summary: Bulk update subscription phases tags: - Subscriptions description: |- Updates multiple subscription phases in a single request. This is useful for reordering phases or making coordinated changes to multiple phases. Returns a dictionary with a `phases` property containing all phases for the subscription after the update, along with metadata about the operation. operationId: bulkUpdateSubscriptionPhases x-frame-sdk: resource: subscriptionPhases method: bulkUpdate security: - BearerAuth: [] parameters: - name: subscription_id in: path required: true description: Subscription ID schema: type: string responses: '200': description: Returns a dictionary with a `phases` property containing all phases for the subscription after the update content: application/json: example: meta: subscription_id: 00000000-0000-4000-8000-000000000001 updated_count: 1 phases: - id: 00000000-0000-4000-8000-000000000002 ordinal: 1 name: pricing_type: relative discount_percentage: '50.0' period_count: 3 phaseable_type: Subscription phaseable_id: 00000000-0000-4000-8000-000000000001 started_at: amount: currency: USD object: subscription_phase created: 1745107200 updated: 1745107200 livemode: false schema: type: object properties: phases: type: array items: type: object properties: id: type: string object: type: string example: subscription_phase ordinal: type: integer description: Position in the phase sequence. Must be unique within the parent resource. name: type: string nullable: true description: Optional descriptive label (e.g. 'Free Trial', 'Introductory Discount') pricing_type: type: string enum: - static - relative description: "'static' — fixed amount in cents. 'relative' — percentage discount off the base price." amount: type: integer nullable: true description: Fixed price in cents. Required when pricing_type is 'static'. currency: type: string nullable: true example: USD discount_percentage: type: string nullable: true description: Percentage discount (0–100), serialized as decimal string (e.g. '50.0'). Required when pricing_type is 'relative'. period_count: type: integer nullable: true description: Number of billing periods this phase lasts. Null means the phase runs indefinitely — no subsequent phases can follow. phaseable_type: type: string description: The parent resource type (Product or Subscription) phaseable_id: type: string description: ID of the parent product or subscription started_at: type: integer nullable: true description: Unix timestamp when this phase became active livemode: type: boolean created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - ordinal - pricing_type - phaseable_type - phaseable_id - livemode - created - updated meta: type: object '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" requestBody: content: application/json: schema: type: object properties: phases: type: array items: type: object description: An array of phase objects to update. Each object should include the phase ID and the fields to update. required: - phases required: true "/v1/subscriptions": get: summary: List subscriptions tags: - Subscriptions description: |- Returns a list of Subscriptions. Results are paginated and returned in reverse chronological order. A dictionary with a `data` property that contains an array of up to `limit` Subscriptions. Each entry in the array is a separate Subscription object. If no more Subscriptions are available, the resulting array will be empty. operationId: getSubscriptions x-frame-sdk: resource: subscriptions method: list security: - BearerAuth: [] parameters: - name: page in: query description: The page offset at which you'd like to resume fetching data. required: false schema: type: integer - name: per_page in: query description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. required: false schema: type: integer responses: '200': description: A paginated list of Subscription objects content: application/json: example: meta: page: 1 url: "/v1/subscriptions" has_more: false prev: next: subscriptions: - id: 00000000-0000-4000-8000-000000000001 description: currency: USD status: active quantity: 1 customer: 00000000-0000-4000-8000-000000000002 account: default_payment_method: object: subscription created: 1745107200 start_date: 1745107200 current_period_start: 1745107200 current_period_end: 1747699200 paused_at: resume_at: livemode: false plan: id: 00000000-0000-4000-8000-000000000003 interval: monthly interval_count: 1 product: 00000000-0000-4000-8000-000000000004 amount: 10000 currency: USD object: plan active: true created: 1745107200 livemode: false phases: [] has_phases: false current_phase: effective_amount: 10000 effective_interval: monthly effective_interval_count: 1 latest_charge: latest_charge_intent: metadata: {} - id: 00000000-0000-4000-8000-000000000005 description: currency: USD status: active quantity: 1 customer: 00000000-0000-4000-8000-000000000002 account: default_payment_method: object: subscription created: 1745107200 start_date: 1745107200 current_period_start: 1745107200 current_period_end: 1747699200 paused_at: resume_at: livemode: false plan: id: 00000000-0000-4000-8000-000000000006 interval: monthly interval_count: 1 product: 00000000-0000-4000-8000-000000000007 amount: 10000 currency: USD object: plan active: true created: 1745107200 livemode: false phases: [] has_phases: false current_phase: effective_amount: 10000 effective_interval: monthly effective_interval_count: 1 latest_charge: latest_charge_intent: metadata: {} - id: 00000000-0000-4000-8000-000000000008 description: currency: USD status: active quantity: 1 customer: 00000000-0000-4000-8000-000000000002 account: default_payment_method: object: subscription created: 1745107200 start_date: 1745107200 current_period_start: 1745107200 current_period_end: 1747699200 paused_at: resume_at: livemode: false plan: id: 00000000-0000-4000-8000-000000000009 interval: monthly interval_count: 1 product: 00000000-0000-4000-8000-000000000010 amount: 10000 currency: USD object: plan active: true created: 1745107200 livemode: false phases: [] has_phases: false current_phase: effective_amount: 10000 effective_interval: monthly effective_interval_count: 1 latest_charge: latest_charge_intent: metadata: {} schema: type: object properties: subscriptions: type: array items: "$ref": "#/components/schemas/Subscription" meta: type: object properties: page: type: integer has_more: type: boolean next: type: string nullable: true prev: type: string nullable: true url: type: string '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" post: summary: Create subscription tags: - Subscriptions description: |- Creates a new subscription on an existing customer. The product's purchase type must be `recurring`. Returns the newly created `Subscription` object, if the call succeeded. If the attempted charge fails, the subscription is created in an `incomplete` status. operationId: createSubscription x-frame-sdk: resource: subscriptions method: create security: - BearerAuth: [] parameters: - name: customer in: query description: The identifier of the customer to subscribe. required: true schema: type: string - name: payment_method in: query description: Payment method ID required: true schema: type: string - name: product in: query description: The ID of the product. The purchase type must be `recurring`. required: true schema: type: string - name: default_payment_method in: query description: ID of the default payment method for the subscription. required: true schema: type: string - name: currency in: query description: Three-letter ISO currency code, in lowercase. Must be a supported currency. required: true schema: type: string - name: billing_interval in: query enum: - month - year description: "Billing interval:\n * `month` \n * `year` \n " required: false schema: type: string - name: trial_period_days in: query description: Trial period in days required: false schema: type: integer - name: metadata in: query description: JSON string of additional custom metadata required: false schema: type: string responses: '200': description: The newly created Subscription object content: application/json: example: id: 00000000-0000-4000-8000-000000000001 description: currency: USD status: active quantity: 1 customer: 00000000-0000-4000-8000-000000000002 account: default_payment_method: 00000000-0000-4000-8000-000000000003 object: subscription created: 1745107200 start_date: 1745107200 current_period_start: 1745107200 current_period_end: 1747699200 paused_at: resume_at: livemode: false plan: id: 00000000-0000-4000-8000-000000000004 interval: monthly interval_count: 1 product: 00000000-0000-4000-8000-000000000005 amount: 10000 currency: USD object: plan active: true created: 1745107200 livemode: false phases: [] has_phases: false current_phase: effective_amount: 10000 effective_interval: monthly effective_interval_count: 1 latest_charge: id: 00000000-0000-4000-8000-000000000006 currency: usd failure_code: failure_message: failure_category: description: Subscription creation status: succeeded acquirer_reference_number: authorization_code: SANDBOX000001 object: charge payment_method_details: id: 00000000-0000-4000-8000-000000000003 customer_id: 00000000-0000-4000-8000-000000000002 account_id: billing: type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '03' exp_year: '30' issuer: currency: segment: type: last_four: '4242' customer: 00000000-0000-4000-8000-000000000002 account: account_id: payment_method: 00000000-0000-4000-8000-000000000003 amount: 10000 amount_captured: 0 amount_refunded: 0 created: 1745107200 updated: 1745107200 livemode: false captured: true disputed: false charge_intent: 00000000-0000-4000-8000-000000000007 refunded: false net_amount: 9611 latest_charge_intent: 00000000-0000-4000-8000-000000000007 metadata: {} schema: "$ref": "#/components/schemas/Subscription" '400': description: Bad request - validation errors content: application/json: schema: "$ref": "#/components/schemas/Error" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/subscriptions/{id}": get: summary: Get subscription tags: - Subscriptions description: |- Retrieves the subscription with the given ID. Returns the subscription object. operationId: getSubscription x-frame-sdk: resource: subscriptions method: get security: - BearerAuth: [] parameters: - name: id in: path description: Unique identifier of the subscription. required: true schema: type: string responses: '200': description: The requested Subscription object content: application/json: example: id: 00000000-0000-4000-8000-000000000001 description: currency: USD status: pending quantity: 1 customer: 00000000-0000-4000-8000-000000000002 account: default_payment_method: object: subscription created: 1745107200 start_date: 1745107200 current_period_start: 1745107200 current_period_end: 1747699200 paused_at: resume_at: livemode: false plan: id: 00000000-0000-4000-8000-000000000003 interval: monthly interval_count: 1 product: 00000000-0000-4000-8000-000000000004 amount: 10000 currency: USD object: plan active: true created: 1745107200 livemode: false phases: [] has_phases: false current_phase: effective_amount: 10000 effective_interval: monthly effective_interval_count: 1 latest_charge: latest_charge_intent: metadata: {} schema: "$ref": "#/components/schemas/Subscription" '404': description: Subscription not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" patch: summary: Update subscription tags: - Subscriptions description: |- Updates an existing subscription to match the specified parameters. Any parameters not provided will be left unchanged. Returns the newly updated `Subscription` object. operationId: updateSubscription x-frame-sdk: resource: subscriptions method: update security: - BearerAuth: [] parameters: - name: id in: path description: Unique identifier of the subscription. required: true schema: type: string - name: default_payment_method in: query description: ID of the default payment method for the subscription. It must belong to the customer associated with the subscription. required: false schema: type: string - name: description in: query description: The subscription's description, meant to be displayable to the customer. required: false schema: type: string responses: '200': description: The updated Subscription object content: application/json: example: id: 00000000-0000-4000-8000-000000000001 description: New description currency: USD status: pending quantity: 1 customer: 00000000-0000-4000-8000-000000000002 account: default_payment_method: object: subscription created: 1745107200 start_date: 1745107200 current_period_start: 1745107200 current_period_end: 1747699200 paused_at: resume_at: livemode: false plan: id: 00000000-0000-4000-8000-000000000003 interval: monthly interval_count: 1 product: 00000000-0000-4000-8000-000000000004 amount: 10000 currency: USD object: plan active: true created: 1745107200 livemode: false phases: [] has_phases: false current_phase: effective_amount: 10000 effective_interval: monthly effective_interval_count: 1 latest_charge: latest_charge_intent: metadata: {} schema: "$ref": "#/components/schemas/Subscription" '404': description: Subscription not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/subscriptions/{id}/cancel": post: summary: Cancel subscription tags: - Subscriptions description: |- Cancels a customer's subscription immediately. The customer will not be charged again for the subscription. Returns the canceled `Subscription` object. Its subscription status will be set to `canceled`. operationId: cancelSubscription x-frame-sdk: resource: subscriptions method: cancel security: - BearerAuth: [] parameters: - name: id in: path description: Unique identifier of the subscription to cancel. required: true schema: type: string - name: cancel_at_period_end in: query description: Whether to cancel at the end of the current period required: false schema: type: boolean - name: reason in: query description: Reason for cancellation required: false schema: type: string responses: '200': description: The canceled Subscription object with status set to `canceled` content: application/json: example: id: 00000000-0000-4000-8000-000000000001 description: currency: USD status: canceled quantity: 1 customer: 00000000-0000-4000-8000-000000000002 account: default_payment_method: object: subscription created: 1745107200 start_date: 1745107200 current_period_start: 1745107200 current_period_end: 1747699200 paused_at: resume_at: livemode: false plan: id: 00000000-0000-4000-8000-000000000003 interval: monthly interval_count: 1 product: 00000000-0000-4000-8000-000000000004 amount: 10000 currency: USD object: plan active: true created: 1745107200 livemode: false phases: [] has_phases: false current_phase: effective_amount: 10000 effective_interval: monthly effective_interval_count: 1 latest_charge: latest_charge_intent: metadata: {} schema: "$ref": "#/components/schemas/Subscription" '404': description: Subscription not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/subscriptions/{id}/pause": post: summary: Pause subscription tags: - Subscriptions description: |- Pauses an active subscription immediately. While paused, renewal is frozen and the subscription remains visible with status `paused`. Returns the paused `Subscription` object. operationId: pauseSubscription x-frame-sdk: resource: subscriptions method: pause security: - BearerAuth: [] parameters: - name: id in: path description: Unique identifier of the subscription to pause. required: true schema: type: string - name: resume_at in: query format: date_time description: Optional scheduled resume time for the current pause. required: false schema: type: string responses: '200': description: The paused Subscription object with status set to `paused` content: application/json: example: id: 00000000-0000-4000-8000-000000000001 description: currency: USD status: paused quantity: 1 customer: 00000000-0000-4000-8000-000000000002 account: default_payment_method: 00000000-0000-4000-8000-000000000003 object: subscription created: 1745107200 start_date: 1745107200 current_period_start: 1745107200 current_period_end: 1746316800 paused_at: 1745107200 resume_at: 1745539200 livemode: false plan: id: 00000000-0000-4000-8000-000000000004 interval: monthly interval_count: 1 product: 00000000-0000-4000-8000-000000000005 amount: 10000 currency: USD object: plan active: true created: 1745107200 livemode: false phases: [] has_phases: false current_phase: effective_amount: 10000 effective_interval: monthly effective_interval_count: 1 latest_charge: latest_charge_intent: metadata: {} schema: "$ref": "#/components/schemas/Subscription" '400': description: Validation error - e.g. subscription is not in a pauseable state content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Subscription not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/subscriptions/{id}/resume": post: summary: Resume subscription tags: - Subscriptions description: |- Resumes a paused subscription. Resuming is money-neutral and shifts the billing anchors by the paused duration. Returns the resumed `Subscription` object. operationId: resumeSubscription x-frame-sdk: resource: subscriptions method: resume security: - BearerAuth: [] parameters: - name: id in: path description: Unique identifier of the subscription to resume. required: true schema: type: string responses: '200': description: The resumed Subscription object with status set to `active` content: application/json: example: id: 00000000-0000-4000-8000-000000000001 description: currency: USD status: active quantity: 1 customer: 00000000-0000-4000-8000-000000000002 account: default_payment_method: 00000000-0000-4000-8000-000000000003 object: subscription created: 1745107200 start_date: 1745107200 current_period_start: 1745193600 current_period_end: 1747785600 paused_at: resume_at: livemode: false plan: id: 00000000-0000-4000-8000-000000000004 interval: monthly interval_count: 1 product: 00000000-0000-4000-8000-000000000005 amount: 10000 currency: USD object: plan active: true created: 1745107200 livemode: false phases: [] has_phases: false current_phase: effective_amount: 10000 effective_interval: monthly effective_interval_count: 1 latest_charge: latest_charge_intent: metadata: {} schema: "$ref": "#/components/schemas/Subscription" '400': description: Validation error - e.g. subscription is not in a resumeable state content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Subscription not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/subscriptions/search": get: summary: Search subscriptions tags: - Subscriptions description: |- Search for subscriptions you've previously created using Frame's Search Query Language. Don't use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages. Returns a dictionary with a `data` property that contains an array of up to `limit` subscriptions. If no objects match the query, the resulting array will be empty. operationId: searchSubscriptions x-frame-sdk: resource: subscriptions method: search security: - BearerAuth: [] parameters: - name: customer in: query description: Filter by customer ID required: false schema: type: string - name: status in: query enum: - pending - active - paused - terminated - canceled - incomplete - past_due - unpaid description: "The status of the subscription. One of `pending`, `active`, `paused`, `terminated`, `canceled`, `incomplete`, `past_due`, or `unpaid`.:\n * `pending` \n * `active` \n * `paused` \n * `terminated` \n * `canceled` \n * `incomplete` \n * `past_due` \n * `unpaid` \n " required: false schema: type: string - name: created_before in: query description: Time at which the object was created. Measured in seconds since the Unix epoch. required: false schema: type: integer - name: created_after in: query description: Time at which the object was created. Measured in seconds since the Unix epoch. required: false schema: type: integer - name: page in: query description: The page offset at which you'd like to resume fetching data. required: false schema: type: integer - name: per_page in: query description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. required: false schema: type: integer responses: '200': description: A paginated list of Subscription objects matching the search criteria content: application/json: example: meta: page: 1 url: "/v1/subscriptions/search?customer=00000000-0000-4000-8000-000000000001&status=active" has_more: false prev: next: subscriptions: - id: 00000000-0000-4000-8000-000000000002 description: currency: USD status: active quantity: 1 customer: 00000000-0000-4000-8000-000000000001 account: default_payment_method: object: subscription created: 1745107200 start_date: 1745107200 current_period_start: 1745107200 current_period_end: 1747699200 paused_at: resume_at: livemode: false plan: id: 00000000-0000-4000-8000-000000000003 interval: monthly interval_count: 1 product: 00000000-0000-4000-8000-000000000004 amount: 10000 currency: USD object: plan active: true created: 1745107200 livemode: false phases: [] has_phases: false current_phase: effective_amount: 10000 effective_interval: monthly effective_interval_count: 1 latest_charge: latest_charge_intent: metadata: {} - id: 00000000-0000-4000-8000-000000000005 description: currency: USD status: active quantity: 1 customer: 00000000-0000-4000-8000-000000000001 account: default_payment_method: object: subscription created: 1745107200 start_date: 1745107200 current_period_start: 1745107200 current_period_end: 1747699200 paused_at: resume_at: livemode: false plan: id: 00000000-0000-4000-8000-000000000006 interval: monthly interval_count: 1 product: 00000000-0000-4000-8000-000000000007 amount: 10000 currency: USD object: plan active: true created: 1745107200 livemode: false phases: [] has_phases: false current_phase: effective_amount: 10000 effective_interval: monthly effective_interval_count: 1 latest_charge: latest_charge_intent: metadata: {} schema: type: object properties: subscriptions: type: array items: "$ref": "#/components/schemas/Subscription" meta: type: object properties: page: type: integer has_more: type: boolean next: type: string nullable: true prev: type: string nullable: true url: type: string '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/terms_of_service": post: summary: Create terms of service token tags: - Terms Of Service description: Generate a short-lived terms of service token for the authenticated merchant. Pass this token to the update endpoint once the user has accepted the terms. operationId: createTermsOfServiceToken x-frame-sdk: resource: termsOfService method: createToken security: - BearerAuth: [] responses: '200': description: Token created successfully content: application/json: example: token: tos_sandbox_000000000000000000000001 schema: type: object properties: token: type: string description: Short-lived terms of service token required: - token '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" patch: summary: Accept terms of service tags: - Terms Of Service description: Record acceptance of the terms of service using a token obtained from the create endpoint. operationId: acceptTermsOfService x-frame-sdk: resource: termsOfService method: update security: - BearerAuth: [] parameters: [] responses: '200': description: Terms of service accepted content: application/json: example: token: tos_sandbox_000000000000000000000001 schema: type: object properties: token: type: string description: Updated terms of service token required: - token '404': description: Token not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '422': description: Validation error content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" requestBody: content: application/json: schema: type: object properties: token: type: string description: Terms of service token from the create endpoint required: - token "/v1/transfer_billing_agreements": get: summary: List transfer billing agreements tags: - Transfers description: Returns a paginated list of transfer billing agreements for the authenticated merchant. operationId: listTransferBillingAgreements x-frame-sdk: resource: transferBillingAgreements method: list security: - BearerAuth: [] parameters: - name: page in: query required: false schema: type: integer - name: per_page in: query required: false description: Max 100 schema: type: integer responses: '200': description: Billing agreements retrieved content: application/json: example: meta: page: 1 url: "/v1/transfer_billing_agreements" has_more: false prev: next: data: - id: 00000000-0000-4000-8000-000000000001 status: pending category: charge effective_date: '2025-04-20T00:00:00.000Z' object: transfer_billing_agreement account_id: created: 1745107200 updated: 1745107200 fee_plan: id: 00000000-0000-4000-8000-000000000002 name: Standard Platform Fee fee_application_mode: deduct object: transfer_fee_plan created: 1745107200 updated: 1745107200 items: [] - id: 00000000-0000-4000-8000-000000000003 status: active category: charge effective_date: '2025-04-20T00:00:00.000Z' object: transfer_billing_agreement account_id: created: 1745107200 updated: 1745107200 fee_plan: id: 00000000-0000-4000-8000-000000000004 name: Standard Platform Fee fee_application_mode: deduct object: transfer_fee_plan created: 1745107200 updated: 1745107200 items: [] - id: 00000000-0000-4000-8000-000000000005 status: active category: payout effective_date: '2025-04-20T00:00:00.000Z' object: transfer_billing_agreement account_id: created: 1745107200 updated: 1745107200 fee_plan: id: 00000000-0000-4000-8000-000000000004 name: Standard Platform Fee fee_application_mode: deduct object: transfer_fee_plan created: 1745107200 updated: 1745107200 items: [] schema: type: object properties: data: type: array items: type: object properties: id: type: string object: type: string example: transfer_billing_agreement status: type: string enum: - pending - active - inactive description: Agreement lifecycle status category: type: string enum: - charge - payout description: Whether this agreement governs charge transfers or payout transfers effective_date: type: string description: ISO 8601 date when the agreement takes effect account_id: type: string nullable: true description: Account this agreement is associated with fee_plan: type: object description: The transfer fee plan governing how fees are calculated properties: id: type: string object: type: string example: transfer_fee_plan name: type: string fee_application_mode: type: string created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - status - category - effective_date - created - updated meta: "$ref": "#/components/schemas/PaginationMeta" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" post: summary: Create a transfer billing agreement tags: - Transfers description: |- Creates a transfer billing agreement, linking a fee plan to an account. Billing agreements determine which fee plan applies when transfers are made for or to a specific account. Provide either a charge or payout category to govern the corresponding transfer type. operationId: createTransferBillingAgreement x-frame-sdk: resource: transferBillingAgreements method: create security: - BearerAuth: [] parameters: - name: transfer_fee_plan_id in: query required: true description: ID of the fee plan to apply schema: type: string - name: category in: query required: true description: charge or payout schema: type: string - name: effective_date in: query required: true description: ISO 8601 date when this agreement takes effect schema: type: string - name: account_id in: query required: false description: Account to associate with this agreement schema: type: string - name: status in: query required: false description: pending (default) or active schema: type: string responses: '201': description: Billing agreement created content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: pending category: charge effective_date: '2025-04-20T00:00:00.000Z' object: transfer_billing_agreement account_id: created: 1745107200 updated: 1745107200 fee_plan: id: 00000000-0000-4000-8000-000000000002 name: Standard Platform Fee fee_application_mode: deduct object: transfer_fee_plan created: 1745107200 updated: 1745107200 items: [] schema: type: object properties: id: type: string object: type: string example: transfer_billing_agreement status: type: string enum: - pending - active - inactive description: Agreement lifecycle status category: type: string enum: - charge - payout description: Whether this agreement governs charge transfers or payout transfers effective_date: type: string description: ISO 8601 date when the agreement takes effect account_id: type: string nullable: true description: Account this agreement is associated with fee_plan: type: object description: The transfer fee plan governing how fees are calculated properties: id: type: string object: type: string example: transfer_fee_plan name: type: string fee_application_mode: type: string created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - status - category - effective_date - created - updated '422': description: Validation error content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/transfer_billing_agreements/{id}": get: summary: Retrieve a transfer billing agreement tags: - Transfers description: Retrieves a transfer billing agreement by ID, including the associated fee plan. operationId: getTransferBillingAgreement x-frame-sdk: resource: transferBillingAgreements method: get security: - BearerAuth: [] parameters: - name: id in: path required: true description: Billing agreement ID schema: type: string responses: '200': description: Billing agreement retrieved content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: pending category: charge effective_date: '2025-04-20T00:00:00.000Z' object: transfer_billing_agreement account_id: created: 1745107200 updated: 1745107200 fee_plan: id: 00000000-0000-4000-8000-000000000002 name: Standard Platform Fee fee_application_mode: deduct object: transfer_fee_plan created: 1745107200 updated: 1745107200 items: [] schema: type: object properties: id: type: string object: type: string example: transfer_billing_agreement status: type: string enum: - pending - active - inactive description: Agreement lifecycle status category: type: string enum: - charge - payout description: Whether this agreement governs charge transfers or payout transfers effective_date: type: string description: ISO 8601 date when the agreement takes effect account_id: type: string nullable: true description: Account this agreement is associated with fee_plan: type: object description: The transfer fee plan governing how fees are calculated properties: id: type: string object: type: string example: transfer_fee_plan name: type: string fee_application_mode: type: string created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - status - category - effective_date - created - updated '404': description: Billing agreement not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" patch: summary: Update a transfer billing agreement tags: - Transfers description: Updates a transfer billing agreement. Currently only the status can be updated. operationId: updateTransferBillingAgreement x-frame-sdk: resource: transferBillingAgreements method: update security: - BearerAuth: [] parameters: - name: id in: path required: true description: Billing agreement ID schema: type: string - name: status in: query required: true description: 'New status: pending, active, or inactive' schema: type: string responses: '200': description: Billing agreement updated content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: pending category: charge effective_date: '2025-04-20T00:00:00.000Z' object: transfer_billing_agreement account_id: created: 1745107200 updated: 1745107200 fee_plan: id: 00000000-0000-4000-8000-000000000002 name: Standard Platform Fee fee_application_mode: deduct object: transfer_fee_plan created: 1745107200 updated: 1745107200 items: [] schema: type: object properties: id: type: string object: type: string example: transfer_billing_agreement status: type: string enum: - pending - active - inactive description: Agreement lifecycle status category: type: string enum: - charge - payout description: Whether this agreement governs charge transfers or payout transfers effective_date: type: string description: ISO 8601 date when the agreement takes effect account_id: type: string nullable: true description: Account this agreement is associated with fee_plan: type: object description: The transfer fee plan governing how fees are calculated properties: id: type: string object: type: string example: transfer_fee_plan name: type: string fee_application_mode: type: string created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - status - category - effective_date - created - updated '404': description: Billing agreement not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/transfer_fee_plans": get: summary: List transfer fee plans tags: - Transfers description: Returns a paginated list of transfer fee plans for the authenticated merchant. operationId: listTransferFeePlans x-frame-sdk: resource: transferFeePlans method: list security: - BearerAuth: [] parameters: - name: page in: query required: false schema: type: integer - name: per_page in: query required: false description: Max 100 schema: type: integer responses: '200': description: Fee plans retrieved content: application/json: example: meta: page: 1 url: "/v1/transfer_fee_plans" has_more: false prev: next: data: - id: 00000000-0000-4000-8000-000000000001 name: Standard Platform Fee fee_application_mode: deduct object: transfer_fee_plan created: 1745107200 updated: 1745107200 items: [] - id: 00000000-0000-4000-8000-000000000002 name: Standard Platform Fee fee_application_mode: deduct object: transfer_fee_plan created: 1745107200 updated: 1745107200 items: [] schema: type: object properties: data: type: array items: type: object properties: id: type: string object: type: string example: transfer_fee_plan name: type: string description: Descriptive name for the fee plan fee_application_mode: type: string enum: - deduct - add_on - absorb description: "'deduct' — fees subtracted from transfer amount. 'add_on' — fees charged in addition. 'absorb' — platform absorbs fees." items: type: array items: type: object properties: id: type: string object: type: string example: transfer_fee_plan_item fee_type: type: string description: Fee calculation method (e.g. percentage, flat, flat_plus_percentage) amount_fixed_cents: type: integer description: Fixed fee component in cents amount_fixed_currency: type: string example: USD amount_percentage: type: number description: Percentage fee component (e.g. 2.5 for 2.5%) billable_event_type: type: string enum: - transfer.charge.card - transfer.charge.ach - transfer.payout.ach - transfer.payout.push_to_card description: The transfer event that triggers this fee min_cap_cents: type: integer nullable: true description: Minimum fee floor in cents, in `amount_fixed_currency`. Only applies to `percentage` and `flat_plus_percentage` items. `null` when no floor is configured — an omitted cap is never treated as a $0 floor. example: max_cap_cents: type: integer nullable: true description: Maximum fee ceiling in cents, in `amount_fixed_currency`. Only applies to `percentage` and `flat_plus_percentage` items. `null` when no ceiling is configured. example: created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - fee_type - amount_fixed_cents - amount_percentage - billable_event_type - created - updated description: Fee line items defining the pricing structure created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - name - fee_application_mode - items - created - updated meta: "$ref": "#/components/schemas/PaginationMeta" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" post: summary: Create a transfer fee plan tags: - Transfers description: Creates a transfer fee plan defining how fees are calculated and applied to transfers. Fee plans are attached to billing agreements which associate them with specific accounts. operationId: createTransferFeePlan x-frame-sdk: resource: transferFeePlans method: create security: - BearerAuth: [] parameters: - name: name in: query required: true description: Descriptive name schema: type: string - name: fee_application_mode in: query required: true description: deduct, add_on, or absorb schema: type: string responses: '201': description: Fee plan created content: application/json: example: id: 00000000-0000-4000-8000-000000000001 name: Standard Platform Fee fee_application_mode: deduct object: transfer_fee_plan created: 1745107200 updated: 1745107200 items: [] schema: type: object properties: id: type: string object: type: string example: transfer_fee_plan name: type: string description: Descriptive name for the fee plan fee_application_mode: type: string enum: - deduct - add_on - absorb description: "'deduct' — fees subtracted from transfer amount. 'add_on' — fees charged in addition. 'absorb' — platform absorbs fees." items: type: array items: type: object properties: id: type: string object: type: string example: transfer_fee_plan_item fee_type: type: string description: Fee calculation method (e.g. percentage, flat, flat_plus_percentage) amount_fixed_cents: type: integer description: Fixed fee component in cents amount_fixed_currency: type: string example: USD amount_percentage: type: number description: Percentage fee component (e.g. 2.5 for 2.5%) billable_event_type: type: string enum: - transfer.charge.card - transfer.charge.ach - transfer.payout.ach - transfer.payout.push_to_card description: The transfer event that triggers this fee min_cap_cents: type: integer nullable: true description: Minimum fee floor in cents, in `amount_fixed_currency`. Only applies to `percentage` and `flat_plus_percentage` items. `null` when no floor is configured — an omitted cap is never treated as a $0 floor. example: max_cap_cents: type: integer nullable: true description: Maximum fee ceiling in cents, in `amount_fixed_currency`. Only applies to `percentage` and `flat_plus_percentage` items. `null` when no ceiling is configured. example: created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - fee_type - amount_fixed_cents - amount_percentage - billable_event_type - created - updated description: Fee line items defining the pricing structure created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - name - fee_application_mode - items - created - updated '422': description: Validation error content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" requestBody: content: application/json: schema: type: array items: type: object properties: fee_type: type: string enum: - flat - percentage - flat_plus_percentage description: Fee calculation method amount_fixed_cents: type: integer description: Fixed fee component in cents amount_fixed_currency: type: string example: USD amount_percentage: type: number description: Percentage fee component (e.g. 2.5 for 2.5%) billable_event_type: type: string enum: - transfer.charge.card - transfer.charge.ach - transfer.payout.ach - transfer.payout.push_to_card description: The transfer event that triggers this fee min_cap_cents: type: integer nullable: true description: Optional minimum fee floor in cents. Allowed only on `percentage` and `flat_plus_percentage` items. Omit or send null for no floor; an omitted cap is not a $0 floor. max_cap_cents: type: integer nullable: true description: Optional maximum fee ceiling in cents. Allowed only on `percentage` and `flat_plus_percentage` items. Must be greater than `min_cap_cents` when both are present. required: - fee_type - billable_event_type description: Fee line items array "/v1/transfer_fee_plans/{id}": get: summary: Retrieve a transfer fee plan tags: - Transfers description: Retrieves a transfer fee plan by ID, including all fee line items. operationId: getTransferFeePlan x-frame-sdk: resource: transferFeePlans method: get security: - BearerAuth: [] parameters: - name: id in: path required: true description: Fee plan ID schema: type: string responses: '200': description: Fee plan retrieved content: application/json: example: id: 00000000-0000-4000-8000-000000000001 name: Standard Platform Fee fee_application_mode: deduct object: transfer_fee_plan created: 1745107200 updated: 1745107200 items: [] schema: type: object properties: id: type: string object: type: string example: transfer_fee_plan name: type: string description: Descriptive name for the fee plan fee_application_mode: type: string enum: - deduct - add_on - absorb description: "'deduct' — fees subtracted from transfer amount. 'add_on' — fees charged in addition. 'absorb' — platform absorbs fees." items: type: array items: type: object properties: id: type: string object: type: string example: transfer_fee_plan_item fee_type: type: string description: Fee calculation method (e.g. percentage, flat, flat_plus_percentage) amount_fixed_cents: type: integer description: Fixed fee component in cents amount_fixed_currency: type: string example: USD amount_percentage: type: number description: Percentage fee component (e.g. 2.5 for 2.5%) billable_event_type: type: string enum: - transfer.charge.card - transfer.charge.ach - transfer.payout.ach - transfer.payout.push_to_card description: The transfer event that triggers this fee min_cap_cents: type: integer nullable: true description: Minimum fee floor in cents, in `amount_fixed_currency`. Only applies to `percentage` and `flat_plus_percentage` items. `null` when no floor is configured — an omitted cap is never treated as a $0 floor. example: max_cap_cents: type: integer nullable: true description: Maximum fee ceiling in cents, in `amount_fixed_currency`. Only applies to `percentage` and `flat_plus_percentage` items. `null` when no ceiling is configured. example: created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - fee_type - amount_fixed_cents - amount_percentage - billable_event_type - created - updated description: Fee line items defining the pricing structure created: type: integer description: Unix timestamp updated: type: integer description: Unix timestamp required: - id - object - name - fee_application_mode - items - created - updated '404': description: Fee plan not found content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/transfers": get: summary: List transfers tags: - Transfers description: Returns all transfers for the authenticated merchant, ordered by most recently created. Results are scoped to the current environment (test vs. live mode). operationId: listTransfers x-frame-sdk: resource: transfers method: list security: - BearerAuth: [] parameters: - name: page in: query required: false description: Page number. schema: type: integer - name: per_page in: query required: false description: Number of results per page. schema: type: integer responses: '200': description: Returns a paginated list of transfer objects. content: application/json: example: meta: page: 1 url: "/v1/transfers" has_more: false prev: next: data: - id: 00000000-0000-4000-8000-000000000001 status: pending description: failure_reason: object: transfer amount: 10000 currency: USD platform_fee: 100 frame_fee: 15 total_fees: 115 gross_amount: 10000 net_amount: 9885 livemode: false created: 1745107200 account: 00000000-0000-4000-8000-000000000002 account_id: 00000000-0000-4000-8000-000000000002 seller_id: charge_intent: payout: billing_agreement: client_secret: metadata: {} source_payment_method: id: 00000000-0000-4000-8000-000000000003 customer_id: account_id: billing: type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '10' exp_year: '30' issuer: currency: segment: type: last_four: '4242' destination_payment_method: id: 00000000-0000-4000-8000-000000000004 customer_id: account_id: billing: type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '02' exp_year: '30' issuer: currency: segment: type: last_four: '4242' schema: type: object properties: data: type: array items: "$ref": "#/components/schemas/Transfer" meta: "$ref": "#/components/schemas/PaginationMeta" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" post: summary: Create transfer tags: - Transfers description: |- Creates a new transfer. Provide `source_payment_method_id` for inbound (charge) flows or `destination_payment_method_id` for outbound (payout) flows. For charge flows, the source payment method is charged and the transfer moves to `succeeded`. For payout flows, the transfer starts as `pending` and transitions to `processing`, then `succeeded` or `failed` once the processor responds. operationId: createTransfer x-frame-sdk: resource: transfers method: create security: - BearerAuth: [] parameters: [] responses: '201': description: Returns the created transfer object. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: pending description: failure_reason: object: transfer amount: 10000 currency: USD platform_fee: 100 frame_fee: 15 total_fees: 115 gross_amount: 10000 net_amount: 9885 livemode: false created: 1745107200 account: 00000000-0000-4000-8000-000000000002 account_id: 00000000-0000-4000-8000-000000000002 seller_id: charge_intent: payout: billing_agreement: client_secret: metadata: {} source_payment_method: destination_payment_method: id: 00000000-0000-4000-8000-000000000003 customer_id: account_id: billing: type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '04' exp_year: '30' issuer: currency: segment: type: last_four: '4242' schema: "$ref": "#/components/schemas/Transfer" '422': description: Validation error content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" requestBody: content: application/json: schema: type: object properties: amount: type: integer description: Amount in the smallest currency unit (e.g. `10000` for $100.00). Must be greater than 0. account_id: type: string description: ID of the account associated with the transfer. currency: type: string description: ISO currency code (e.g. `USD`). Defaults to `USD`. source_payment_method_id: type: string description: Required for charge flows. The payment method to charge. Omit for payout flows. destination_payment_method_id: type: string description: Required for payout flows (must be ACH or debit card). Optional for charge flows — when provided, funds go to the account that owns the payment method; when omitted, funds go to the merchant. seller_id: type: string description: ID of a business account under your merchant to attribute this charge to (the Seller). Records the Seller on the underlying charge and upserts the Buyer↔Seller Patronage roster. The Buyer (`account_id`) remains the charged party. Only supported for charge-backed transfers (requires `source_payment_method_id`). description: type: string description: Arbitrary description for your records. metadata: type: object description: Key-value pairs to attach to the transfer. confirm: type: boolean description: Whether to immediately confirm the transfer. Defaults to `true`. Setting to `false` returns the transfer in `requires_confirmation` for later confirmation via `POST /v1/transfers/:id/confirm`. Only supported for charge-backed transfers. promotion_codes: type: array items: type: string description: Promotion code identifiers to apply as discounts on the underlying charge. Only supported for charge-backed transfers (requires `source_payment_method_id`). Invalid codes are silently skipped; the transfer proceeds without their discount. sonar_session_id: type: string description: Identifier for an existing fraud-evaluation session (also known as `charge_session_id`) to attach to the underlying charge. Only supported for charge-backed transfers (requires `source_payment_method_id`). required: - amount - account_id "/v1/transfers/{id}": get: summary: Get transfer tags: - Transfers description: Retrieves the details of an existing transfer by its ID. Returns the transfer object if found. operationId: getTransfer x-frame-sdk: resource: transfers method: get security: - BearerAuth: [] parameters: - name: id in: path description: The ID of the transfer to retrieve. required: true schema: type: string responses: '200': description: Returns the transfer object. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 status: pending description: failure_reason: object: transfer amount: 10000 currency: USD platform_fee: 100 frame_fee: 15 total_fees: 115 gross_amount: 10000 net_amount: 9885 livemode: false created: 1745107200 account: 00000000-0000-4000-8000-000000000002 account_id: 00000000-0000-4000-8000-000000000002 seller_id: charge_intent: payout: billing_agreement: client_secret: metadata: {} source_payment_method: id: 00000000-0000-4000-8000-000000000003 customer_id: account_id: billing: type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '09' exp_year: '30' issuer: currency: segment: type: last_four: '4242' destination_payment_method: id: 00000000-0000-4000-8000-000000000004 customer_id: account_id: billing: type: card object: payment_method created: 1745107200 updated: 1745107200 livemode: false status: active card: brand: visa exp_month: '12' exp_year: '30' issuer: currency: segment: type: last_four: '4242' schema: "$ref": "#/components/schemas/Transfer" '404': description: Transfer not found '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/webhook_endpoints": get: summary: List webhook endpoints tags: - Webhooks description: |- Returns a list of webhook endpoints configured for the authenticated merchant. You can configure webhook endpoints via the API to be notified about events that happen in your Frame account. Most users configure webhooks from the dashboard, which provides a user interface for registering your webhook endpoints. For security, the signing `secret` is **not** included on list or retrieve responses. It is returned only when you create an endpoint or rotate its secret. If you've lost a secret, rotate it to obtain a new one. operationId: listWebhookEndpoints x-frame-sdk: resource: webhookEndpoints method: list security: - BearerAuth: [] parameters: - name: page in: query required: false description: Page number for pagination. schema: type: integer - name: per_page in: query required: false description: Number of results per page. schema: type: integer responses: '200': description: A paginated list of webhook endpoints. content: application/json: example: meta: page: 1 url: "/v1/webhook_endpoints" has_more: false prev: next: data: [] schema: type: object properties: data: type: array items: type: object meta: "$ref": "#/components/schemas/PaginationMeta" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" post: summary: Create webhook endpoint tags: - Webhooks description: Creates a webhook endpoint. Provide an HTTPS URL and the list of event codes you want delivered. The response includes the signing `secret`; surface it to the user once — it can be rotated later via `/v1/webhook_endpoints/{id}/rotate_secret`. operationId: createWebhookEndpoint security: - BearerAuth: [] parameters: [] responses: '201': description: Returns the created webhook endpoint, including its signing secret. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 description: Test livemode: false event_codes: - charge.captured status: active url: https://example.com/hook created: 1745107200 updated: 1745107200 object: webhook_endpoint secret: 1 schema: type: object '400': description: Bad request — invalid URL or event_codes contains unknown values. '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" requestBody: content: application/json: schema: type: object required: - url - event_codes properties: url: type: string description: HTTPS URL Frame will POST events to. description: type: string description: Optional human-readable description. event_codes: type: array items: type: string description: List of event codes to subscribe to. Must be drawn from the canonical event-code catalog. "/v1/webhook_endpoints/{id}": get: summary: Retrieve webhook endpoint tags: - Webhooks description: Retrieves a webhook endpoint by ID. The signing `secret` is not included — it is returned only on create and rotate-secret. Rotate the secret if you need a new value. operationId: getWebhookEndpoint security: - BearerAuth: [] parameters: - name: id in: path description: Unique identifier for the webhook endpoint. required: true schema: type: string responses: '200': description: Returns the webhook endpoint. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 description: Sint ut et. livemode: false event_codes: - account.activated - customer.updated status: active url: https://example.com/webhook created: 1745107200 updated: 1745107200 object: webhook_endpoint schema: type: object '404': description: Webhook endpoint not found. content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" patch: summary: Update webhook endpoint tags: - Webhooks description: Updates the URL, description, or subscribed event codes for a webhook endpoint. operationId: updateWebhookEndpoint security: - BearerAuth: [] parameters: - name: id in: path description: Unique identifier for the webhook endpoint. required: true schema: type: string responses: '200': description: Returns the updated webhook endpoint. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 description: Voluptatem nobis sed. livemode: false event_codes: - charge_intent.expired - charge_intent.remaining_voided status: active url: https://example.com/new created: 1745107200 updated: 1745107200 object: webhook_endpoint schema: type: object '400': description: Bad request '404': description: Webhook endpoint not found. content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" requestBody: content: application/json: schema: type: object properties: url: type: string description: HTTPS URL Frame will POST events to. description: type: string description: Optional human-readable description. event_codes: type: array items: type: string description: Replacement list of event codes. delete: summary: Delete webhook endpoint tags: - Webhooks description: Soft-deletes a webhook endpoint. After deletion Frame stops delivering events to this URL. operationId: deleteWebhookEndpoint security: - BearerAuth: [] parameters: - name: id in: path description: Unique identifier for the webhook endpoint. required: true schema: type: string responses: '200': description: Returns a deletion stub. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 object: webhook_endpoint deleted: true schema: type: object properties: id: type: string description: Webhook endpoint ID object: type: string description: Object type deleted: type: boolean description: Deletion status '404': description: Webhook endpoint not found. content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" "/v1/webhook_endpoints/{id}/rotate_secret": post: summary: Rotate webhook signing secret tags: - Webhooks description: Rotates the signing secret for a webhook endpoint. The new secret is returned once in the response — store it securely. The previous secret is immediately invalidated, so configure verifiers with the new value before continuing to process events. operationId: rotateWebhookEndpointSecret security: - BearerAuth: [] parameters: - name: id in: path description: Unique identifier for the webhook endpoint. required: true schema: type: string responses: '200': description: Returns the webhook endpoint with the rotated secret. content: application/json: example: id: 00000000-0000-4000-8000-000000000001 description: Deleniti autem ea. livemode: false event_codes: - transfer_billing_agreement.updated - subscription.incomplete status: active url: https://example.com/webhook created: 1745107200 updated: 1745107200 object: webhook_endpoint secret: 1 schema: type: object '400': description: Validation failed during rotation. '404': description: Webhook endpoint not found. content: application/json: schema: "$ref": "#/components/schemas/NotFoundError" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/AuthError" tags: - name: Accounts description: Create and manage connected accounts. Accounts represent the merchants or end users on your platform who send payments, receive payouts, and complete verification flows. Create an account with the capabilities you need, prefill any information you already have, and use hosted onboarding to collect the rest. - name: Customers description: Create and manage customers. Customers represent the end users or businesses transacting on your platform and are the anchor for payment methods, subscriptions, and invoices. - name: Charge Intents description: Create and manage charge intents. A charge intent represents a payment attempt and tracks it through the authorization, capture, and settlement lifecycle. It is the primary object you create to initiate a payment on your platform. - name: Charges description: Retrieve charges created from charge intents. A charge is the settled record of a successful payment. - name: Payment Methods description: Create and manage payment methods. Payment methods represent the funding instruments — cards, bank accounts — attached to customers or accounts. - name: Subscriptions description: Create and manage subscriptions. Subscriptions represent recurring billing relationships between your platform and a customer, tied to a product and billing interval. - name: Products description: Create and manage products. Products define the goods or services you offer, along with their pricing, billing interval, and phase schedules. - name: Invoices description: Create and manage invoices. Invoices are statements of amounts owed, generated automatically for subscriptions or created manually for one-time charges. - name: Refunds description: Create and retrieve refunds. Refunds return all or part of a charge back to the original payment method. - name: Disputes description: Retrieve and respond to disputes. A dispute (chargeback) occurs when a cardholder questions a charge with their bank. Use this API to submit evidence. - name: Transfers description: Create and retrieve transfers. Transfers move funds between your platform and connected accounts. - name: Payouts description: Create payouts. Payouts disburse funds from your merchant balance to an external bank account or card. - name: Coupons description: Create and manage coupon templates. Coupons define the discount rules — percentage or fixed — that promotion codes are generated from. - name: Promotion Codes description: Create and manage promotion codes. Promotion codes are the customer-facing discount codes generated from coupon templates and applied at checkout. - name: Discounts description: Retrieve and validate discounts. Discounts are applied coupon or promotion code reductions on a charge intent or invoice. - name: Billing description: Usage-based billing. Define billing metrics (meters) to track usage events, then generate invoices and reports against accumulated usage. - name: Webhooks description: Manage webhook endpoints. Frame sends real-time event notifications to your registered endpoints as objects on your account change state. - name: KYC Prefill description: Confirm KYC prefill data on an account. When you create an account using prefill (Prove live data or sandbox seed data), the account holder must confirm the prefilled identity information before Frame treats it as verified. This endpoint records that confirmation along with the caller's IP and user-agent as evidence of consent, and emits the `frame.account.prefill.completed` event. - name: 3DS Intents description: Create and poll 3D Secure verification intents. During client-side checkout the SDK creates a 3DS intent for a payment method, redirects the cardholder to the issuer challenge, and polls the intent for completion. Callable with a publishable key. servers: - url: https://api.framepayments.com description: Production server - url: https://api.staging.framepayments.com description: Staging server - url: https://api.framepayments.test description: Development server components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: Use your secret API key (sk_sandbox_... or sk_production_...) PublishableKey: type: http scheme: bearer bearerFormat: JWT description: Use your publishable API key (pk_sandbox_... or pk_production_...) schemas: PaginationMeta: type: object description: Pagination metadata returned on all list responses properties: page: type: integer description: Current page number example: 1 per_page: type: integer description: Items per page example: 10 total: type: integer description: Total count of items example: 42 has_more: type: boolean description: Whether more pages exist example: false prev: type: integer nullable: true description: Previous page number, or null on the first page example: next: type: integer nullable: true description: Next page number, or null on the last page example: url: type: string description: Base URL for this list example: "/v1/accounts" Error: type: object properties: type: type: string description: Machine-readable error type (e.g. `invalid_request`, `authentication_error`) example: invalid_request message: type: string description: Human-readable error message example: The provided API key is invalid. data: type: object nullable: true description: Additional structured error data, if any example: required: - type - message AuthError: type: object properties: status: type: integer description: HTTP status code example: 401 error: type: string description: Error message example: Unauthorized required: - status - error NotFoundError: type: object properties: status: type: integer description: HTTP status code example: 404 error: type: string description: Error message example: Not Found code: type: string description: Machine-readable error code example: not_found error_details: nullable: true description: Validation detail (string or field-keyed object), 422 responses oneOf: - type: string - type: object required: - status - error - code ValidationError: type: object properties: errors: oneOf: - type: string description: Simple error message example: type is required - type: object description: Field-level validation errors keyed by field name example: type: - must be filled required: - errors Charge: type: object description: A charge created from a charge intent properties: id: type: string description: Unique identifier for the charge example: b72fce52-eb12-5704-91a4-e3da890fb648 object: type: string description: Object type identifier. Always `charge`. example: charge amount: type: integer description: Amount charged in cents example: 2000 currency: type: string description: Three-letter ISO currency code example: usd status: type: string description: Charge status. One of `pending`, `succeeded`, or `failed`. example: succeeded livemode: type: boolean description: "`true` if live mode, `false` if test mode" example: false created: type: integer description: Unix timestamp of creation example: 1721010605 charge_intent_id: type: string nullable: true description: ID of the charge intent that created this charge example: a70cd72f-e74a-40f2-96a2-3f60714aac4a required: - id - object - amount - currency - status - created - livemode Dispute: type: object description: A dispute occurs when a customer questions a charge with their card issuer. properties: id: type: string description: Unique identifier for the dispute. example: 388f584c-0003-4470-9c52-667a3dd71e0b status: type: string description: Current dispute status. Possible values include `received`, `warning_needs_response`, `warning_under_review`, `warning_closed`, `needs_response`, `under_review`, `won`, and `lost`. example: needs_response display_status: type: string description: Human-readable status for display in dashboards. example: Under review amount_cents: type: integer description: Disputed amount in the smallest currency unit (e.g. cents for USD). example: 2000 amount_currency: type: string description: Three-letter ISO currency code (uppercase) for the disputed amount. example: USD reason: type: object description: Reason given by the cardholder for the dispute. Fields may be null until the issuer reports them. properties: code: type: string nullable: true description: Machine-readable reason code. example: fraudulent description: type: string nullable: true description: Human-readable description of the reason. example: Cardholder claims the charge is fraudulent. category: type: string nullable: true description: Broad category for the reason. example: fraud acquirer_reference_number: type: string nullable: true description: Reference number assigned by the acquirer for tracking. example: '24692160000000123456789' authorization_code: type: string nullable: true description: Authorization code from the original transaction. example: A1B2C3 charge_intent: "$ref": "#/components/schemas/ChargeIntent" livemode: type: boolean description: "`true` if live mode, `false` if test mode." example: false updated: type: integer description: Unix timestamp of last update. example: 1721010705 required: - id - status - display_status - reason - amount_cents - amount_currency - livemode - updated Customer: type: object properties: id: type: string description: Unique identifier for the customer example: 235978d1-9081-45ce-a57d-e0a9659e8880 object: type: string description: Object type identifier. Always `customer`. example: customer email: type: string format: email description: Customer email address example: marcia@example.com name: type: string nullable: true description: Customer full name example: Marcia Longo phone: type: string nullable: true description: Customer phone number example: "+13107484186" livemode: type: boolean description: "`true` if live mode, `false` if test mode" example: false created_at: type: string format: date-time example: '2024-07-15T10:30:05Z' updated_at: type: string format: date-time example: '2024-07-15T10:30:05Z' required: - id - email ChargeIntent: type: object properties: id: type: string description: Unique identifier for the charge intent example: a70cd72f-e74a-40f2-96a2-3f60714aac4a object: type: string description: Object type identifier. Always `charge_intent`. example: charge_intent amount: type: integer description: Amount to be charged in cents example: 2000 currency: type: string description: Three-letter ISO currency code example: usd status: type: string description: Current status. One of `incomplete`, `requires_payment_method`, `requires_3d_secure`, `processing`, `succeeded`, `failed`, or `canceled`. example: incomplete livemode: type: boolean description: "`true` if live mode, `false` if test mode" example: false created: type: integer description: Unix timestamp of creation example: 1721010605 client_secret: type: string description: Client secret used by Frame.js to confirm the charge intent on the frontend example: ci_a70cd72f_secret_xk3m2n9p authorization_mode: type: string description: How the charge is authorized. One of `automatic` or `manual`. example: automatic description: type: string nullable: true description: An optional description of what is being charged example: failure_description: type: string nullable: true description: Human-readable reason the charge failed, if applicable example: reference_id: type: string nullable: true description: Merchant-defined reference inherited from the payment link this charge was created through. Returned verbatim here and in `charge_intent` webhook events. example: user_8675309 customer_id: type: string nullable: true description: ID of the customer associated with this charge intent, if any. Always returned. example: cus_1a2b3c customer: type: object nullable: true description: The full customer object. Only returned to secret-key requests; omitted for publishable-key responses (use `customer_id`). account_id: type: string nullable: true description: ID of the connected account associated with this charge intent, if any. Always returned. example: account: type: object nullable: true description: The full connected-account object. Only returned to secret-key requests; omitted for publishable-key responses (use `account_id`). payment_method: type: object nullable: true description: The payment method being charged, if any. Returns the full payment method object. subscription: type: string nullable: true description: ID of the subscription this charge intent belongs to, if any example: invoice: type: string nullable: true description: ID of the invoice this charge intent is associated with, if any example: latest_charge: type: object nullable: true description: The most recent charge created from this intent, if any. Returns the full charge object. shipping: type: object nullable: true description: Shipping address associated with this charge intent example: metadata: type: object description: Set of key-value pairs for your own reference. Only returned to secret-key requests; omitted for publishable-key responses. example: {} revenue_split: type: object nullable: true description: Revenue-split configuration and recipient. Merchant-internal — only returned to secret-key requests; omitted for publishable-key responses. example: required: - id - amount - currency - status - object - created - livemode PaymentMethod: type: object properties: id: type: string description: Unique identifier for the payment method example: c4d5e6f7-1234-5678-abcd-9e0a1b2c3d4e object: type: string description: Object type identifier. Always `payment_method`. example: payment_method type: type: string description: Type of payment method. One of `card` or `ach`. example: card status: type: string description: Status. One of `active`, `blocked`, or `detached`. example: active created: type: integer description: Unix timestamp of creation example: 1721010605 updated: type: integer description: Unix timestamp of last update example: 1721010605 livemode: type: boolean description: "`true` if live mode, `false` if test mode" example: false customer_id: type: string nullable: true description: ID of the customer this payment method is attached to example: 235978d1-9081-45ce-a57d-e0a9659e8880 account_id: type: string nullable: true description: ID of the account this payment method is attached to example: card: type: object nullable: true description: Card details. Present when `type` is `card`. properties: brand: type: string description: Card brand (e.g. `visa`, `mastercard`) example: visa last_four: type: string description: Last four digits of the card number example: '4242' exp_month: type: string description: Two-digit expiration month example: '12' exp_year: type: string description: Four-digit expiration year example: '2027' wallet: type: object nullable: true description: Wallet details. Present only for Apple Pay / Google Pay payment methods. properties: type: type: string description: Wallet type. One of `apple_pay` or `google_pay`. example: apple_pay dynamic_last4: type: string description: Last four digits of the device-specific account number. example: '4242' single_use: type: boolean description: 'Always `true`: wallet credentials carry a single-use device cryptogram and cannot be charged more than once. Collect a fresh wallet authorization for each charge.' example: true consumed: type: boolean description: "`true` once the credential has been used. A consumed wallet payment method cannot be charged again — reuse is rejected with code `payment_method_single_use`." example: false ach: type: object nullable: true description: ACH bank account details. Present when `type` is `ach`. properties: bank_name: type: string description: Name of the bank institution example: Chase last_four: type: string description: Last four digits of the account number example: '6789' account_type: type: string description: Account type. One of `checking` or `savings`. example: checking billing: type: object nullable: true description: Billing address associated with this payment method example: required: - id - object - type - status - created - livemode BeneficialOwner: type: object description: A beneficial owner linked to a business account. properties: id: type: string description: Unique identifier for the beneficial owner. example: b5d7c8e9-1234-5678-abcd-9e0a1b2c3d4e object: type: string description: Object type identifier. Always `beneficial_owner`. example: beneficial_owner account_id: type: string description: ID of the owner's individual account. example: 7b0d0f8c-6df6-4aa1-b229-0c95e5f2b14c first_name: type: string description: First name. example: Janet middle_name: type: string nullable: true description: Middle name. example: last_name: type: string description: Last name. example: Jones suffix: type: string nullable: true description: Name suffix. example: email: type: string format: email description: Email address. example: janet@example.com roles: type: array items: type: string description: Role designations for the representative. example: - owner - controller percent_ownership: type: number nullable: true description: Declared ownership percentage. example: 50 status: type: string description: Current owner status. example: completed livemode: type: boolean description: "`true` if live mode, `false` if test mode." example: false created: type: integer description: Unix timestamp of creation. example: 1721010605 updated: type: integer description: Unix timestamp of last update. example: 1721010705 required: - id - object - account_id - first_name - last_name - email - roles - status - created - updated - livemode Product: type: object properties: id: type: string description: Unique identifier for the product example: d5e6f7g8-2345-6789-bcde-0f1a2b3c4d5e object: type: string description: Object type identifier. Always `product`. example: product name: type: string description: Product name shown on invoices and receipts example: Platform Plus description: type: string nullable: true description: Optional product description example: Full-featured platform plan with priority support created: type: integer description: Unix timestamp of creation example: 1721010605 updated: type: integer description: Unix timestamp of last update example: 1721010605 livemode: type: boolean description: "`true` if live mode, `false` if test mode" example: false active: type: boolean description: "`true` if the product is available for purchase" example: true metadata: type: object description: Set of key-value pairs for your own reference example: {} required: - id - name - object - created - livemode Subscription: type: object properties: id: type: string description: Unique identifier for the subscription example: e6f7g8h9-3456-7890-cdef-1a2b3c4d5e6f object: type: string description: Object type identifier. Always `subscription`. example: subscription customer: type: string description: ID of the customer this subscription belongs to example: 235978d1-9081-45ce-a57d-e0a9659e8880 status: type: string description: Current status. One of `pending`, `active`, `paused`, `past_due`, `unpaid`, `incomplete`, `canceled`, or `terminated`. example: active created: type: integer description: Unix timestamp of creation example: 1721010605 updated: type: integer description: Unix timestamp of last update example: 1721010605 livemode: type: boolean description: "`true` if live mode, `false` if test mode" example: false current_period_start: type: integer nullable: true description: Unix timestamp of the start of the current billing period example: 1721010605 current_period_end: type: integer nullable: true description: Unix timestamp of the end of the current billing period example: 1723689005 paused_at: type: integer nullable: true description: Unix timestamp of when the subscription entered the current paused state, if paused. example: 1721010605 resume_at: type: integer nullable: true description: Unix timestamp of the scheduled resume time for the current pause, if one is set. example: 1721270605 metadata: type: object description: Set of key-value pairs for your own reference example: {} required: - id - customer - status - object - created - livemode Invoice: type: object properties: id: type: string description: Unique identifier for the invoice example: f7g8h9i0-4567-8901-defa-2b3c4d5e6f7a object: type: string description: Object type identifier. Always `invoice`. example: invoice invoice_number: type: string description: Human-readable invoice number example: INV-0042 total: type: integer description: Total amount in cents example: 5000 currency: type: string description: Three-letter ISO currency code example: usd status: type: string description: Current status. One of `draft`, `open`, `paid`, `void`, or `uncollectible`. example: open collection_method: type: string description: How payment is collected. One of `charge_automatically` or `request_payment`. example: charge_automatically subscription_id: type: string nullable: true description: ID of the subscription this invoice belongs to, if any example: billing_reason: type: string nullable: true description: Why this invoice was created. One of `subscription_create`, `subscription_cycle`, `subscription_update`, `manual`, or `usage`. example: manual net_terms: type: integer description: Payment terms in days example: 30 due_date: type: string nullable: true description: Invoice due date in ISO 8601 format example: '2024-08-14' description: type: string nullable: true description: Optional invoice description example: memo: type: string nullable: true description: Optional memo shown on the invoice example: customer: type: object nullable: true description: The customer this invoice is for, if any account: type: object nullable: true description: The account this invoice is for, if any line_items: type: array items: "$ref": "#/components/schemas/InvoiceLineItem" description: Line items on this invoice metadata: type: object description: Set of key-value pairs for your own reference example: {} livemode: type: boolean description: "`true` if live mode, `false` if test mode" example: false created: type: integer description: Unix timestamp of creation example: 1721010605 updated: type: integer description: Unix timestamp of last update example: 1721010605 required: - id - object - invoice_number - total - currency - status - collection_method - created - updated - livemode - net_terms - line_items - metadata InvoiceLineItem: type: object properties: id: type: string description: Unique identifier for the line item example: h9i0j1k2-6789-0123-fabc-4d5e6f7a8b9c object: type: string description: Object type identifier. Always `invoice_line_item`. example: invoice_line_item description: type: string description: Product name or description shown on the invoice example: Platform Plus — Jul 2024 quantity: type: integer description: Number of units example: 1 unit_amount_cents: type: integer description: Price per unit in cents example: 5000 unit_amount_currency: type: string description: Three-letter ISO currency code example: USD created: type: integer description: Unix timestamp of creation example: 1721010605 updated: type: integer description: Unix timestamp of last update example: 1721010605 required: - id - object - description - quantity - unit_amount_cents - unit_amount_currency - created - updated CapabilityError: type: object description: A verification error attached to a capability. Cleared automatically when the underlying requirement is verified or waived. properties: id: type: string description: Unique identifier for the capability error. example: f8a3b1c2-d4e5-6789-abcd-ef1234567890 object: type: string description: Object type identifier. Always `capability_error`. example: capability_error code: type: string description: Machine-readable error code (e.g. `invalid_phone_number`). example: invalid_phone_number message: type: string nullable: true description: Human-readable description of the error. example: The phone number provided could not be verified requirement_id: type: string description: ID of the requirement that produced this error. example: b2c3d4e5-f6a7-8901-bcde-f12345678901 created: type: integer description: Unix timestamp of when the error was created. example: 1721003405 required: - id - object - code - requirement_id - created Capability: type: object description: A capability attached to an account, controlling what verification flows run and what payment methods the account can use. properties: id: type: string description: Unique identifier for the capability. example: a1b2c3d4-e5f6-7890-abcd-ef1234567891 object: type: string description: Object type identifier. Always `capability`. example: capability name: type: string description: The capability type. One of `kyc`, `phone_verification`, `kyc_prefill`, `age_verification`, `address_verification`, `card_verification`, `bank_account_verification`, `creator_shield`, `geo_compliance`, `card_send`, `card_receive`, `bank_account_send`, or `bank_account_receive`. enum: - kyc - phone_verification - kyc_prefill - age_verification - address_verification - card_verification - bank_account_verification - creator_shield - geo_compliance - card_send - card_receive - bank_account_send - bank_account_receive example: kyc account_id: type: string description: ID of the account this capability belongs to. example: 99c6b0da-2570-42a7-838a-5eaa318b07df status: type: string description: Current status. One of `pending`, `active`, or `disabled`. enum: - pending - active - disabled example: pending disabled_reason: type: string nullable: true description: Why the capability is disabled. Present only when `status` is `disabled`. example: currently_due: type: array items: type: string description: Field keys still required before this capability can activate. Empty when already `active`. example: - profile.individual.name - profile.individual.address - profile.individual.ssn_last_four errors: type: array items: "$ref": "#/components/schemas/CapabilityError" description: Errors from failed requirement verifications. Cleared automatically when the requirement is verified or waived. example: [] created: type: string format: date-time description: ISO 8601 timestamp of when the capability was created. example: '2024-07-15T01:10:05Z' updated: type: string format: date-time description: ISO 8601 timestamp of when the capability was last updated. example: '2024-07-15T01:10:05Z' disabled: type: string format: date-time nullable: true description: ISO 8601 timestamp of when the capability was disabled. `null` if not disabled. example: required: - id - object - name - account_id - status - currently_due - errors - created - updated Wallet: type: object properties: id: type: string description: Unique identifier for the wallet example: g8h9i0j1-5678-9012-efab-3c4d5e6f7a8b object: type: string description: Object type identifier. Always `wallet`. example: wallet balance: type: integer description: Current total balance in cents example: 100000 currency: type: string description: Three-letter ISO currency code example: usd available_balance: type: integer description: Balance available for immediate use in cents example: 90000 pending_balance: type: integer description: Balance held pending settlement in cents example: 10000 created: type: integer description: Unix timestamp of creation example: 1721010605 updated: type: integer description: Unix timestamp of last update example: 1721010605 livemode: type: boolean description: "`true` if live mode, `false` if test mode" example: false last_transaction_at: type: integer nullable: true description: Unix timestamp of the most recent transaction example: 1721010605 required: - id - balance - currency - object - created - livemode Transfer: type: object description: A transfer represents the movement of funds associated with an account. Charge flows debit a source payment method; payout flows push funds to a destination payment method. properties: id: type: string description: Unique identifier for the transfer. example: e36c1cc2-d9f0-44db-a522-12b0aab990db object: type: string description: Object type identifier. Always `transfer`. example: transfer status: type: string description: Current status. One of `pending`, `incomplete`, `requires_account_or_customer`, `requires_payment_method`, `requires_confirmation`, `requires_3d_secure`, `requires_capture`, `processing`, `succeeded`, `failed`, `expired`, `canceled`, `reversed`, `refunded`, or `disputed`. enum: - pending - incomplete - requires_account_or_customer - requires_payment_method - requires_confirmation - requires_3d_secure - requires_capture - processing - succeeded - failed - expired - canceled - reversed - refunded - disputed example: pending amount: type: integer description: Requested transfer amount in the smallest currency unit (e.g. cents). `10000` represents $100.00. example: 10000 currency: type: string description: Three-letter ISO currency code in uppercase (e.g. `USD`). example: USD platform_fee: type: integer description: Fee earned by the platform on this transfer, in cents. example: 100 frame_fee: type: integer description: Frame's processing fee for this transfer, in cents. example: 15 total_fees: type: integer description: Sum of `platform_fee` and `frame_fee` in cents. example: 115 gross_amount: type: integer description: Gross transaction amount in cents. For charge flows in `add_on` mode this is the grossed-up amount; otherwise equals `amount`. example: 10000 net_amount: type: integer description: Amount received by the payee in cents after fees. example: 9885 description: type: string nullable: true description: Optional description provided at creation. example: Weekly payout failure_reason: type: string nullable: true description: Human-readable reason when `status` is `failed`. `null` otherwise. example: charge_intent: type: string nullable: true description: ID of the associated charge intent for charge flows. `null` for payout flows. example: payout: type: string nullable: true description: ID of the associated payout for payout flows. `null` for charge flows. example: billing_agreement: type: string nullable: true description: ID of the billing agreement used to calculate fees. example: b37da62b-c233-4358-967a-7910656fb94f client_secret: type: string nullable: true description: Client secret for deferred-confirm flows. `null` for standard payout flows. example: account: type: string description: ID of the account associated with this transfer. example: c1a4a27f-d6e4-46e2-9557-fd5faaa31e7d account_id: type: string description: ID of the account associated with this transfer. This is the Buyer — the charged party. example: c1a4a27f-d6e4-46e2-9557-fd5faaa31e7d seller_id: type: string nullable: true description: ID of the business account this charge was attributed to (the Seller). Attribution only — the Buyer (`account_id`) remains the charged party. `null` when no Seller was named. example: source_payment_method: type: object nullable: true description: The payment method charged in charge flows. `null` for payout flows. properties: id: type: string description: Payment method ID. example: 2a769159-83b7-4b78-8a07-3e5891a414d2 object: type: string description: Always `payment_method`. example: payment_method type: type: string description: Payment method type. One of `card` or `ach`. example: card status: type: string description: Payment method status. example: active livemode: type: boolean description: "`true` if live mode." example: false created: type: integer description: Unix timestamp of creation. example: 1773398080 updated: type: integer description: Unix timestamp of last update. example: 1773398080 destination_payment_method: type: object nullable: true description: The payment method funds are sent to in payout flows. `null` when omitted in charge flows. properties: id: type: string description: Payment method ID. example: 2a769159-83b7-4b78-8a07-3e5891a414d2 object: type: string description: Always `payment_method`. example: payment_method type: type: string description: Payment method type. One of `ach` or `card`. example: ach status: type: string description: Payment method status. example: active livemode: type: boolean description: "`true` if live mode." example: false created: type: integer description: Unix timestamp of creation. example: 1773398080 updated: type: integer description: Unix timestamp of last update. example: 1773398080 metadata: type: object description: Key-value pairs attached to the transfer for your own reference. example: {} livemode: type: boolean description: "`true` if the transfer exists in live mode, `false` for test mode." example: false created: type: integer description: Unix timestamp of when the transfer was created. example: 1773415510 required: - id - object - status - amount - currency - platform_fee - frame_fee - total_fees - gross_amount - net_amount - account - account_id - metadata - livemode - created Account: type: object properties: id: type: string example: 99c6b0da-2570-42a7-838a-5eaa318b07df description: Unique identifier for the account object: type: string example: account description: Object type identifier. Always `account`. type: type: string enum: - individual - business example: individual description: Account type. One of `individual` or `business`. status: type: string enum: - pending - active - restricted - disabled example: active description: Current status. One of `pending`, `active`, `restricted`, or `disabled`. external_id: type: string nullable: true example: usr_8675309 description: An optional identifier from your own system. Must be unique per merchant. metadata: type: object example: {} description: A set of key-value pairs you can attach to the account for your own reference. Merchant-internal — only returned to secret-key requests; omitted for publishable-key responses. additionalProperties: true payout_payment_method_id: type: string nullable: true example: description: ID of the payment method used for payouts to this account. Merchant-internal — only returned to secret-key requests; omitted for publishable-key responses. profile: type: object nullable: true description: The account holder's profile (PII). Contains either an `individual` or `business` sub-object depending on account type. Only returned to secret-key requests, or to an onboarding-session client secret reading its own account; omitted for publishable-key responses. properties: individual: type: object description: Individual account holder profile. properties: name: type: object description: Legal name of the account holder. example: first_name: Marcia middle_name: last_name: Longo suffix: properties: first_name: type: string description: First name. example: Marcia middle_name: type: string nullable: true description: Middle name. example: last_name: type: string description: Last name. example: Longo suffix: type: string nullable: true description: Name suffix (e.g. `Jr.`, `Sr.`). example: email: type: string description: The individual's email address. example: marcia@example.com phone: type: object description: Phone number for the account holder. example: number: '3107484186' country_code: '1' properties: number: type: string nullable: true description: Phone number. example: '3107484186' country_code: type: string nullable: true description: Country calling code (e.g. `"1"` for US). example: '1' ssn_last_four: type: string nullable: true example: '6789' description: Last four digits of the SSN. The full SSN is accepted during onboarding, stored encrypted, and never returned in full. birthdate: type: string format: date nullable: true description: Date of birth in `YYYY-MM-DD` format. Required for KYC and age verification. example: address: type: object nullable: true description: Residential address. example: line_1: 123 Main St line_2: city: Los Angeles state: CA postal_code: '90001' country: US properties: line_1: type: string description: Street address line 1. example: 123 Main St line_2: type: string nullable: true description: Street address line 2. example: city: type: string description: City. example: Los Angeles state: type: string description: State or province code (e.g. `"CA"`). example: CA postal_code: type: string description: Postal or ZIP code. example: '90001' country: type: string description: Two-letter ISO country code (e.g. `"US"`). example: US business: type: object description: Business account profile. properties: legal_business_name: type: string description: The registered legal name of the business. example: Acme Corp doing_business_as: type: string nullable: true description: Trade name if different from the legal name. example: business_type: type: string example: llc description: Business entity type (e.g. `llc`, `corporation`, `sole_proprietorship`). email: type: string description: Business email address. example: billing@acme.com phone: type: object description: Business phone number. example: number: '2125550100' country_code: '1' properties: number: type: string nullable: true description: Phone number. example: '2125550100' country_code: type: string nullable: true description: Country calling code (e.g. `"1"` for US). example: '1' website: type: string nullable: true description: The business's website URL. example: https://acme.com description: type: string nullable: true description: A description of the business. example: ein: type: string nullable: true example: description: Employer Identification Number. Stored encrypted — only the last four digits are returned. mcc: type: string nullable: true description: Merchant Category Code. example: '5734' naics: type: string nullable: true description: NAICS industry classification code. example: '519130' same_physical_and_legal_address: type: boolean description: Whether the business operates from its registered legal address. When `true`, the legal `address` is also used as the physical address; when `false`, a separate physical address is collected. example: true address: type: object nullable: true description: Business legal address — the registered address of the business. example: line_1: 100 Broadway line_2: Suite 200 city: New York state: NY postal_code: '10005' country: US properties: line_1: type: string description: Street address line 1. example: 100 Broadway line_2: type: string nullable: true description: Street address line 2. example: Suite 200 city: type: string description: City. example: New York state: type: string description: State or province code (e.g. `"NY"`). example: NY postal_code: type: string description: Postal or ZIP code. example: '10005' country: type: string description: Two-letter ISO country code (e.g. `"US"`). example: US physical_address: type: object nullable: true description: Business physical address — where the business actually operates. Populated only when `same_physical_and_legal_address` is `false`; `null` otherwise (the legal `address` is the physical address). example: line_1: 55 Market St line_2: Floor 3 city: San Francisco state: CA postal_code: '94105' country: US properties: line_1: type: string description: Street address line 1. example: 55 Market St line_2: type: string nullable: true description: Street address line 2. example: Floor 3 city: type: string description: City. example: San Francisco state: type: string description: State or province code (e.g. `"CA"`). example: CA postal_code: type: string description: Postal or ZIP code. example: '94105' country: type: string description: Two-letter ISO country code (e.g. `"US"`). example: US capabilities: type: array description: Capabilities requested for this account. Each object includes `name`, `status`, `currently_due`, and `disabled_reason`. example: - id: a1b2c3d4-e5f6-7890-abcd-ef1234567891 object: capability name: kyc status: active disabled_reason: currently_due: [] disabled: - id: a1b2c3d4-e5f6-7890-abcd-ef1234567892 object: capability name: card_receive status: pending disabled_reason: currently_due: [] disabled: items: type: object properties: id: type: string description: Unique identifier for the capability. example: a1b2c3d4-e5f6-7890-abcd-ef1234567891 object: type: string description: Object type identifier. Always `capability`. example: capability name: type: string description: Capability identifier (e.g. `kyc`, `card_send`, `card_receive`). example: card_send status: type: string description: Current status. One of `active`, `pending`, or `disabled`. example: active disabled_reason: type: string nullable: true description: Human-readable reason the capability is disabled, if applicable. example: currently_due: type: array items: type: string description: Fields required to activate this capability. example: [] disabled: type: string nullable: true description: Non-null if the capability has been explicitly disabled. example: terms_of_service: type: object nullable: true description: Record of when and how the account holder accepted your platform's terms of service. `null` if not yet accepted. example: token: tos_v1_2024 accepted: true accepted_at: '2024-08-24T14:15:22Z' properties: token: type: string nullable: true description: An optional token identifying the specific version of terms accepted. example: tos_v1_2024 accepted: type: boolean description: "`true` if the account holder has accepted the terms of service." example: true accepted_at: type: string format: date-time nullable: true description: ISO 8601 timestamp of when the terms were accepted. example: '2024-08-24T14:15:22Z' steps: type: array description: Ordered onboarding steps for this account. Each step reflects a capability requirement and its current completion status. example: - key: kyc status: pending label: Verify your identity fields: - individual.name.first_name - individual.name.last_name currently_due: - individual.name.first_name items: type: object properties: key: type: string description: Step identifier, matching the capability name (e.g. `kyc`, `card_receive`). example: kyc status: type: string enum: - pending - in_progress - completed - failed description: Current step status. One of `pending`, `in_progress`, `completed`, or `failed`. example: pending label: type: string description: Human-readable step label. example: Verify your identity fields: type: array items: type: string description: All fields associated with this step. example: - individual.name.first_name - individual.name.last_name currently_due: type: array items: type: string description: Fields that must be provided before this step can advance. example: - individual.name.first_name created: type: integer example: 1721010605 description: Unix timestamp of when the account was created updated: type: integer example: 1721010605 description: Unix timestamp of when the account was last updated livemode: type: boolean example: false description: "`true` if the account exists in live mode, `false` if in test mode" required: - id - object - type - status - created - updated - livemode ThreeDSIntent: type: object description: A 3D Secure verification intent. Created for a payment method during client-side checkout; the client drives the issuer challenge and polls this object for completion. properties: id: type: string description: Unique identifier for the 3DS intent. example: 3ds_intent_1a2b3c object: type: string description: String representing the object's type. Always `three_ds_verification_intent`. example: three_ds_verification_intent customer: type: string nullable: true description: ID of the customer associated with the underlying charge intent, if any. example: cus_1a2b3c payment_method: type: string nullable: true description: ID of the payment method being verified. example: pm_1a2b3c status: type: string description: Current status of the verification (e.g. `issued`, `verified`, `failed`). example: issued challenge_url: type: string nullable: true description: URL the client redirects the cardholder to for the issuer challenge. Present while the intent is `issued`, otherwise `null`. example: https://api.framepayments.com/v1/evervault/3ds/callback/3ds_intent_1a2b3c completed: type: integer nullable: true description: Unix timestamp of when verification completed, or `null` while still in progress. example: created: type: integer description: Unix timestamp of when the intent was created. example: 1721010605 updated: type: integer description: Unix timestamp of when the intent was last updated. example: 1721010605 livemode: type: boolean description: "`true` if the intent exists in live mode, `false` in test mode." example: false required: - id - object - status - created - updated - livemode