> ## Documentation Index > Fetch the complete documentation index at: https://juo.dev/llms.txt > Use this file to discover all available pages before exploring further. # Add a payment method > Used to add a payment method to a customer. ## OpenAPI ````yaml openapi-admin.json POST /customers/{customerId}/payment-methods openapi: 3.1.0 info: title: Juo Admin API version: 1.0.0 description: >- Programmatic access to subscription management for merchants. ## Core Resources - **Subscriptions** — the central entity. Belongs to a Customer, contains Items (product variants) and Discounts. Lifecycle: `active` → `paused` or `cancelled`; `paused` → `active` or `cancelled`; `cancelled` → `active` (via reactivate). - **Items** — subscription items (product variants) (quantity, price, billing/delivery policies). - **Discounts** — applied to subscriptions by discount code or manually (percentage or fixed amount, targeting subscription items or shipping). - **Customers** — customers who own subscriptions and payment methods. - **Products / Variants** — catalog products and variants that can be assigned to subscription plans. - **Schedules** — a read-only projection of upcoming billing orders, derived from subscription state, active schedule adjustments, and triggered workflows. **Schedule adjustments never modify the subscription** — they apply changes to upcoming orders matching the specified criteria (by cycle, date, or both), which may cover one or more orders. For permanent changes (billing frequency, items, payment method, delivery address), update the subscription directly. - **Workflows** — interactive customer-facing flows (retention, dunning, onboarding). Contain Steps connected by Transitions and produce Runs on each execution. Supports A/B experiment steps. ## Authentication Every request requires: - `X-Juo-Admin-Api-Key` header — the merchant's Admin API key. - `X-Tenant-ID` header — the store identifier (myshopify domain, e.g. `my-store.myshopify.com`). servers: - url: https://api.juo.io/admin/v1 security: - AdminApiKey: [] - BearerToken: [] tags: - name: subscriptions description: >- Recurring billing agreements with customers. Manage lifecycle (pause, resume, cancel, reactivate), items, and discounts. - name: customers description: Customers who own subscriptions. Create and update customer records. - name: products description: >- Products and variants linked to subscription plans. Manage catalog and plan assignments. - name: schedules description: >- Read-only view of upcoming billing orders generated from subscription state, schedule adjustments, and workflows. Use schedule adjustments for targeted changes to upcoming orders (scoped by cycle number, date, or both) — they never alter the subscription itself. For permanent changes (billing frequency, items, payment method), update the subscription directly. - name: workflows description: >- Interactive customer-facing flows for retention, dunning, and onboarding. Define steps, publish, and track execution runs and experiments. paths: /customers/{customerId}/payment-methods: post: tags: - customers description: Creates a customer payment method parameters: - schema: minLength: 1 type: string in: path name: customerId required: true description: The customer identifier - $ref: '#/components/parameters/TenantHeader' requestBody: content: application/json: schema: anyOf: - additionalProperties: false type: object properties: provider: type: string enum: - bogus - type: object properties: provider: anyOf: - type: string enum: - mollie - type: string enum: - stripe - type: string enum: - tpay - type: string enum: - payu - type: string enum: - paynl externalId: type: string externalCustomerId: type: string instrument: anyOf: - type: object properties: type: type: string enum: - CreditCard brand: type: string expiryMonth: type: integer expiryYear: type: integer lastDigits: minLength: 4 maxLength: 4 type: string name: type: string source: type: string required: - type - brand - expiryMonth - expiryYear - lastDigits - name - type: object properties: type: type: string enum: - SepaDirectDebit consumerName: type: string consumerAccount: type: string consumerBic: type: string signedAt: format: date-time type: string externalMandateId: type: string required: - type - consumerName - consumerAccount - consumerBic - signedAt - type: object properties: type: type: string enum: - BLIK alias: type: object properties: value: type: string label: type: string type: anyOf: - type: string enum: - UID - type: string enum: - PAYID email: format: email type: string appKey: type: string required: - value - label - type - email required: - type - alias - type: object properties: type: type: string enum: - Bacs lastDigits: minLength: 4 maxLength: 4 type: string required: - type - lastDigits required: - provider - instrument responses: '201': description: Default Response content: application/json: schema: $ref: '#/components/schemas/CustomerPaymentMethod' '400': description: >- Bad request — invalid input or violated business rule (e.g., wrong subscription status for the requested operation). '401': description: Unauthorized — missing, expired, or invalid API key. '403': description: Forbidden — authenticated but not permitted to access this resource. '404': description: >- Not found — the resource does not exist or belongs to a different tenant. '422': description: >- Unprocessable entity — well-formed request that fails semantic validation. components: parameters: TenantHeader: name: X-Tenant-ID x-speakeasy-name-override: tenant x-speakeasy-globals-hidden: true in: header schema: type: string required: true description: >- Unique identifier of the tenant in the system (usually a store identifier) schemas: CustomerPaymentMethod: type: object properties: id: format: uuid type: string customer: description: >- Customer `id` when not expanded, or the full `Customer` object when the field name is included in the `expand` query parameter. anyOf: - minLength: 1 description: Customer ID (numeric string). examples: - '7654321' type: string - $ref: '#/components/schemas/Customer' instrument: anyOf: - type: object properties: type: type: string enum: - credit-card brand: minLength: 1 description: Credit card network name. type: string maskedNumber: minLength: 1 description: Masked card number. type: string required: - type - brand - maskedNumber - type: object properties: type: type: string enum: - paypal paypalAccountEmail: format: email description: Email of the associated PayPal account. type: - 'null' - string required: - type - paypalAccountEmail - type: object properties: type: type: string enum: - shop-pay maskedNumber: minLength: 1 description: Masked card number. type: string required: - type - maskedNumber - type: object properties: type: type: string enum: - sepa-direct-debit consumerName: minLength: 1 description: Full name of the account holder. type: string consumerBic: minLength: 1 description: BIC code. type: - 'null' - string maskedConsumerAccount: minLength: 1 description: Masked IBAN. type: string required: - type - consumerName - consumerBic - maskedConsumerAccount - type: object properties: type: type: string enum: - blik required: - type - type: object properties: type: type: string enum: - mbway phone: minLength: 1 type: string required: - type - type: object properties: type: type: string enum: - bacs maskedNumber: minLength: 1 description: Masked number. type: string required: - type - maskedNumber required: - id - customer title: CustomerPaymentMethod Customer: type: object properties: id: minLength: 1 description: Customer ID (numeric string). type: string example: '7654321' resource: type: string enum: - customer displayName: minLength: 1 description: Customer's full name. type: string example: Jane Smith email: format: email description: Customer's contact email. type: - 'null' - string example: jane.smith@example.com phone: minLength: 1 description: Customer's contact phone number in E.164 format. type: - 'null' - string example: '+15550100' required: - id - resource - displayName - email - phone title: Customer securitySchemes: AdminApiKey: type: apiKey name: X-Juo-Admin-Api-Key in: header description: >- Long-lived Admin API key issued from the Juo merchant portal. Pass as the `X-Juo-Admin-Api-Key` header. BearerToken: type: http scheme: bearer bearerFormat: JWT description: >- Short-lived JWT minted via the merchant browser-session flow. Carries the authenticated staff identity so that API calls are attributed to the specific staff user in the activity log. ````