Maxio Wallet Purchases API

openapi: 3.2.0
info:
  title: Maxio Wallet Purchases API
  version: '1.0'
  contact:
    email: support@maxio.com
  description: 'Operations tagged Wallet Purchases across 2 of this provider''s published API definitions: maxio-advanced-billing-openapi31json.json, maxio-advanced-billing-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{site}.chargify.com
  description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
  variables:
    site:
      default: subdomain
      description: The subdomain for your Advanced Billing site.
- url: https://events.chargify.com/{site}
  description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
  variables:
    site:
      default: subdomain
      description: The subdomain for your Advanced Billing site.
- url: https://{site}.ebilling.maxio.com
  description: Advanced Billing environment hosted in EU. Use only when you requested EU hosting for your AB account.
  variables:
    site:
      default: subdomain
      description: The subdomain for your Advanced Billing site.
security:
- BasicAuth: []
tags:
- name: Wallet Purchases
  description: Wallet Purchases let a subscription buy additional prepaid units for a wallet, charged according to the subscription's collection method. A purchase can be previewed to quote the price before anything is charged. For more information, see Understand Wallets.
paths:
  /wallets/{wallet_id}/purchases.json:
    parameters: []
    post:
      tags:
      - Wallet Purchases
      summary: createWalletPurchase
      description: 'Purchases prepaid units for the wallet and charges the subscription''s payment method for them, using the wallet''s `price_point_id` unless a different price point is named. A successful purchase writes a grant of origin `purchase`, with its expiration following the funding entitlement''s grant expiration policy.


        How "charged" works depends on the subscription''s collection method. For card/automatic collection, the payment is attempted immediately; a decline writes nothing to the wallet, and the call fails with a `422` naming the gateway''s decline reason. For invoice-billed (remittance) subscriptions, there''s no immediate charge to decline: an invoice is drafted, the wallet is credited right away, and the invoice is issued afterward. If issuing the invoice fails at that point, the invoice is left in draft state and reported for follow-up, but the call still returns `201` and the units already credited are **not** rolled back. See Preview Wallet Purchase to quote a price before charging anything.'
      operationId: createWalletPurchase
      parameters:
      - name: wallet_id
        in: path
        description: The Advanced Billing id of the wallet.
        required: true
        schema:
          type: integer
          contentEncoding: int32
      - name: Idempotency-Key
        in: header
        description: 'A key you generate, such as a UUID, that makes retrying this request safe. 1 to 255 printable ASCII characters; surrounding double quotes are ignored. Keys are scoped to your site and kept for at least 24 hours.


          The first request with a key runs normally. A retry with the same key, method, path and query string, and a byte-identical body returns the stored status and body of that first request without running it again. The same key with a different request returns `422` (`idempotency_key_mismatch`). A retry that arrives while the first request is still running waits for it to finish, and returns `409` (`idempotency_request_in_progress`) only if that wait times out; on Create Wallet Purchase the `409` is immediate. Only successful responses are stored, so a failed request can be retried with the same key. When this header is sent, `uniqueness_token` is not checked.


          See [Idempotent retries](page:introduction/basic-concepts/wallets#idempotent-retries) for the details, including how wallet purchases differ.'
        schema:
          maxLength: 255
          minLength: 1
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/CreateWalletPurchaseRequest'
              - examples:
                - purchase:
                    quantity: '500.0'
              contentMediaType: application/json
            examples:
              Example:
                value:
                  purchase:
                    quantity: '500.0'
        required: false
      responses:
        '201':
          description: Purchase completed. Charges the subscription's payment method and, once payment succeeds, credits the wallet.
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/WalletPurchaseResultResponse'
                - examples:
                  - wallet_purchases:
                    - id: 15
                      price_point_id: 140
                      invoice_uid: abc123
                      quantity: '500.0'
                      expires_at: null
                    balance: '650.0'
                contentMediaType: application/json
              examples:
                Example:
                  value:
                    wallet_purchases:
                    - id: 15
                      price_point_id: 140
                      invoice_uid: abc123
                      quantity: '500.0'
                      expires_at: null
                    balance: '650.0'
        '400':
          description: The `Idempotency-Key` header is empty, longer than 255 characters, or contains characters other than printable ASCII. Nothing is written.
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/WalletErrorResponse1'
                - description: The JSON error body returned by every wallet, transaction, adjustment, purchase, and Wallet Product endpoint for `400`, `404`, `409`, `422`, `500`, and `503` responses. A `403` is not JSON; it is the plain text `403 Forbidden`.
                  examples:
                  - errors:
                    - Idempotency-Key must be 1 to 255 printable ASCII characters
                    code: idempotency_key_invalid
                contentMediaType: application/json
              examples:
                IdempotencyKeyInvalid:
                  value:
                    errors:
                    - Idempotency-Key must be 1 to 255 printable ASCII characters
                    code: idempotency_key_invalid
        '403':
          description: Forbidden. The response body is plain text (`403 Forbidden`), not JSON. Returned when the Wallets feature isn't enabled for the site.
          headers: {}
          content: {}
        '404':
          description: Not Found
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/WalletErrorResponse1'
                - description: The JSON error body returned by every wallet, transaction, adjustment, purchase, and Wallet Product endpoint for `400`, `404`, `409`, `422`, `500`, and `503` responses. A `403` is not JSON; it is the plain text `403 Forbidden`.
                contentMediaType: application/json
        '409':
          description: 'Returned in two cases, both with nothing new charged or written. `idempotency_request_in_progress`: a purchase with the same `Idempotency-Key` is still running; retry with the same key once it finishes. `idempotency_key_outcome_unknown`: an earlier purchase with this key ended with a server error or an unexpected failure before its result was recorded, so it may or may not have charged the customer. Check the subscription''s invoices before buying again under a new key.'
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/WalletErrorResponse1'
                - description: The JSON error body returned by every wallet, transaction, adjustment, purchase, and Wallet Product endpoint for `400`, `404`, `409`, `422`, `500`, and `503` responses. A `403` is not JSON; it is the plain text `403 Forbidden`.
                  examples:
                  - '{"errors":["A request with this Idempotency-Key is still being processed"],"code":"idempotency_request_in_progress"}'
                  - '{"errors":["The previous purchase with this Idempotency-Key ended without a confirmed result. Check whether it happened before buying again under a new key."],"code":"idempotency_key_outcome_unknown"}'
                contentMediaType: application/json
              examples:
                IdempotencyRequestInProgress:
                  value:
                    errors:
                    - A request with this Idempotency-Key is still being processed
                    code: idempotency_request_in_progress
                IdempotencyKeyOutcomeUnknown:
                  value:
                    errors:
                    - The previous purchase with this Idempotency-Key ended without a confirmed result. Check whether it happened before buying again under a new key.
                    code: idempotency_key_outcome_unknown
        '422':
          description: 'Validation or payment failure, or an `Idempotency-Key` reused with a different request (`idempotency_key_mismatch`). Validation failures include a missing `purchase` root, a missing, malformed, non-positive, or out-of-range `quantity`, a `price_point_id` that doesn''t belong to the wallet''s billing product, an archived, custom, or otherwise unusable price point, no price point to purchase at (neither sent nor set on the wallet), a memo over 255 characters, an archived wallet, a price point with no price in the subscription''s currency, a declined payment (message includes the gateway''s own detail), an invoice that couldn''t be created at all, a payment that settled but whose units could not be credited (`purchase_paid_but_uncredited`, whose message ends with the paid invoice''s uid so it can be reconciled), a declined payment whose invoice could not be voided and is still open (`purchase_declined_invoice_open`), a purchase that failed before payment and left its invoice open (`purchase_invoice_left_open`), and a wallet whose billing product isn''t a Wallet Product (only possible for a wallet created before Wallet Products became required).


            `purchase_paid_but_uncredited`, `purchase_declined_invoice_open` and `purchase_invoice_left_open` bodies also carry `invoice_uid` and `invoice_number`. With an `Idempotency-Key`, these three responses are stored and replayed like a success.'
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/WalletErrorResponse1'
                - description: The JSON error body returned by every wallet, transaction, adjustment, purchase, and Wallet Product endpoint for `400`, `404`, `409`, `422`, `500`, and `503` responses. A `403` is not JSON; it is the plain text `403 Forbidden`.
                  examples:
                  - '{"errors":["This Idempotency-Key was already used with a different request"],"code":"idempotency_key_mismatch"}'
                  - '{"errors":["Payment for this purchase was declined: insufficient funds"],"code":"purchase_payment_declined"}'
                  - '{"errors":["The invoice for this purchase could not be created"],"code":"purchase_invoice_failed"}'
                  - '{"errors":["Purchase was paid but the units could not be credited: inv_abc123"],"code":"purchase_paid_but_uncredited","invoice_uid":"inv_abc123","invoice_number":"1042"}'
                  - '{"errors":["Payment for this purchase was declined and invoice inv_abc123 is still open: insufficient funds"],"code":"purchase_declined_invoice_open","invoice_uid":"inv_abc123","invoice_number":"1042"}'
                  - '{"errors":["The purchase failed before the payment, and invoice inv_abc123 is still open"],"code":"purchase_invoice_left_open","invoice_uid":"inv_abc123","invoice_number":"1042"}'
                contentMediaType: application/json
              examples:
                IdempotencyKeyMismatch:
                  value:
                    errors:
                    - This Idempotency-Key was already used with a different request
                    code: idempotency_key_mismatch
                Declined:
                  value:
                    errors:
                    - 'Payment for this purchase was declined: insufficient funds'
                    code: purchase_payment_declined
                InvoiceFailed:
                  value:
                    errors:
                    - The invoice for this purchase could not be created
                    code: purchase_invoice_failed
                PaidButUncredited:
                  value:
                    errors:
                    - 'Purchase was paid but the units could not be credited: inv_abc123'
                    code: purchase_paid_but_uncredited
                    invoice_uid: inv_abc123
                    invoice_number: '1042'
                DeclinedInvoiceOpen:
                  value:
                    errors:
                    - 'Payment for this purchase was declined and invoice inv_abc123 is still open: insufficient funds'
                    code: purchase_declined_invoice_open
                    invoice_uid: inv_abc123
                    invoice_number: '1042'
                InvoiceLeftOpen:
                  value:
                    errors:
                    - The purchase failed before the payment, and invoice inv_abc123 is still open
                    code: purchase_invoice_left_open
                    invoice_uid: inv_abc123
                    invoice_number: '1042'
        '500':
          description: '`purchase_payment_outcome_unknown`: the payment was attempted but the gateway did not confirm whether the card was charged. Nothing is credited by this call; if the invoice turns out to be paid, the units are credited automatically (see [Purchasing Units](page:introduction/basic-concepts/wallets#purchasing-units)). The body includes `invoice_uid` and `invoice_number` when an invoice was created; check that invoice before buying again. Retrying with the same `Idempotency-Key` returns `409` (`idempotency_key_outcome_unknown`) rather than charging again.'
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/WalletErrorResponse1'
                - description: The JSON error body returned by every wallet, transaction, adjustment, purchase, and Wallet Product endpoint for `400`, `404`, `409`, `422`, `500`, and `503` responses. A `403` is not JSON; it is the plain text `403 Forbidden`.
                  examples:
                  - errors:
                    - The payment for this purchase did not confirm whether the card was charged. Check invoice inv_abc123 before buying again
                    code: purchase_payment_outcome_unknown
                    invoice_uid: inv_abc123
                    invoice_number: '1042'
                contentMediaType: application/json
              examples:
                PaymentOutcomeUnknown:
                  value:
                    errors:
                    - The payment for this purchase did not confirm whether the card was charged. Check invoice inv_abc123 before buying again
                    code: purchase_payment_outcome_unknown
                    invoice_uid: inv_abc123
                    invoice_number: '1042'
      deprecated: false
    servers:
    - url: https://{site}.chargify.com
      description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://events.chargify.com/{site}
      description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://{site}.ebilling.maxio.com
      description: Advanced Billing environment hosted in EU. Use only when you requested EU hosting for your AB account.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://events.chargify.com/{site}
      description: Advanced Billing environment hosted in EU. Use only when you requested EU hosting for your AB account.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
  /wallets/{wallet_id}/purchases/preview.json:
    parameters: []
    post:
      tags:
      - Wallet Purchases
      summary: previewWalletPurchase
      description: Quotes the price for a purchase at the given quantity and price point, without charging the payment method or writing to the wallet. Takes the same parameters as Create Wallet Purchase.
      operationId: previewWalletPurchase
      parameters:
      - name: wallet_id
        in: path
        description: The Advanced Billing id of the wallet.
        required: true
        schema:
          type: integer
          contentEncoding: int32
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/CreateWalletPurchaseRequest'
              - examples:
                - purchase:
                    quantity: '500.0'
              contentMediaType: application/json
            examples:
              Example:
                value:
                  purchase:
                    quantity: '500.0'
        required: false
      responses:
        '200':
          description: A price quote. Charges nothing and writes nothing to the wallet.
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/WalletPurchasePreviewResponse'
                - examples:
                  - wallet_purchase_previews:
                    - price_point_id: 140
                      currency: USD
                      quantity: '500.0'
                      amount: '25.0'
                contentMediaType: application/json
              examples:
                Example:
                  value:
                    wallet_purchase_previews:
                    - price_point_id: 140
                      currency: USD
                      quantity: '500.0'
                      amount: '25.0'
        '403':
          description: Forbidden. The response body is plain text (`403 Forbidden`), not JSON. Returned when the Wallets feature isn't enabled for the site.
          headers: {}
          content: {}
        '404':
          description: Not Found
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/WalletErrorResponse1'
                - description: The JSON error body returned by every wallet, transaction, adjustment, purchase, and Wallet Product endpoint for `400`, `404`, `409`, `422`, `500`, and `503` responses. A `403` is not JSON; it is the plain text `403 Forbidden`.
                contentMediaType: application/json
        '422':
          description: Validation failure. Same cases as Create Wallet Purchase, minus the payment-outcome cases, since nothing is charged.
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/WalletErrorResponse1'
                - description: The JSON error body returned by every wallet, transaction, adjustment, purchase, and Wallet Product endpoint for `400`, `404`, `409`, `422`, `500`, and `503` responses. A `403` is not JSON; it is the plain text `403 Forbidden`.
                contentMediaType: application/json
      deprecated: false
    servers:
    - url: https://{site}.chargify.com
      description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://events.chargify.com/{site}
      description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://{site}.ebilling.maxio.com
      description: Advanced Billing environment hosted in EU. Use only when you requested EU hosting for your AB account.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://events.chargify.com/{site}
      description: Advanced Billing environment hosted in EU. Use only when you requested EU hosting for your AB account.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
components:
  schemas:
    Purchase:
      title: Purchase
      required:
      - quantity
      type: object
      properties:
        quantity:
          oneOf:
          - type: string
          - type: integer
            contentEncoding: int32
          description: 'The number of wallet units to purchase, as a decimal string with at most 8 fractional digits. Send fractional values as strings: a JSON number with a decimal point is rejected with `422`, because a double-precision float may already have lost precision before the request arrives.'
          examples:
          - '500.0'
        price_point_id:
          type: integer
          description: The price point to purchase at. Must belong to the wallet's billing product. Defaults to the `price_point_id` set on the wallet.
          contentEncoding: int32
        memo:
          maxLength: 255
          type:
          - string
          - 'null'
          description: (Optional) A note recorded on the resulting grant's ledger row.
    WalletErrorResponse1:
      title: WalletErrorResponse1
      required:
      - errors
      - code
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
          description: Human-readable messages. These may be reworded, so match on `code` instead.
        code:
          type: string
          description: A stable, machine-readable reason, for example `wallet_depleted`, `wallet_not_found`, `wallet_product_not_found`, `price_point_archived`, `kind_invalid`, or `parameter_missing`. Failures that come from record validation, such as a field that fails a model rule, report `validation_failed`.
          examples:
          - wallet_depleted
        invoice_uid:
          type: string
          description: 'Returned only by Create Wallet Purchase with `purchase_paid_but_uncredited`, `purchase_declined_invoice_open`, `purchase_invoice_left_open` and `purchase_payment_outcome_unknown`: the uid of the invoice the purchase created. Check it before buying again.'
        invoice_number:
          type: string
          description: 'Returned alongside `invoice_uid`: the number of the invoice the purchase created.'
      description: The JSON error body returned by every wallet, transaction, adjustment, purchase, and Wallet Product endpoint for `400`, `404`, `409`, `422`, `500`, and `503` responses. A `403` is not JSON; it is the plain text `403 Forbidden`.
    WalletPurchasePreviewResponse:
      title: WalletPurchasePreviewResponse
      required:
      - wallet_purchase_previews
      type: object
      properties:
        wallet_purchase_previews:
          type: array
          items:
            $ref: '#/components/schemas/WalletPurchasePreview'
          description: ''
    CreateWalletPurchaseRequest:
      title: CreateWalletPurchaseRequest
      required:
      - purchase
      type: object
      properties:
        purchase:
          $ref: '#/components/schemas/Purchase'
      description: Purchases prepaid units for the wallet at a price point, charging the subscription's payment method.
    WalletPurchase:
      title: WalletPurchase
      required:
      - id
      - price_point_id
      - invoice_uid
      - quantity
      - expires_at
      type: object
      properties:
        id:
          type: integer
          description: The id of the grant this purchase created. When the wallet was overdrawn by at least the purchased quantity, the units repay the debt and the grant is still created, with `remaining` of `0` and `original` equal to the purchased quantity.
          contentEncoding: int32
        price_point_id:
          type: integer
          description: The price point the purchase was priced at.
          contentEncoding: int32
        invoice_uid:
          type: string
          description: The uid of the invoice created to collect payment for this purchase.
        quantity:
          type: string
          description: The number of units purchased, as a decimal string.
        expires_at:
          type:
          - string
          - 'null'
          description: When the purchased units expire, following the funding entitlement's grant expiration policy. `null` when the wallet has no funding entitlement or its entitlements disagree on an expiration policy.
          contentEncoding: date-time
      description: A completed unit purchase.
    WalletPurchasePreview:
      title: WalletPurchasePreview
      required:
      - price_point_id
      - currency
      - quantity
      - amount
      type: object
      properties:
        price_point_id:
          type: integer
          contentEncoding: int32
        currency:
          type: string
          description: The three-letter currency code the `amount` is denominated in, matching the subscription's currency.
          examples:
          - USD
        quantity:
          type: string
          description: The number of units the quote is for, as a decimal string.
        amount:
          type: string
          description: The price for `quantity` units at this price point, as a decimal string.
      description: A price quote for a purchase, without charging anything.
    WalletPurchaseResultResponse:
      title: WalletPurchaseResultResponse
      required:
      - wallet_purchases
      - balance
      type: object
      properties:
        wallet_purchases:
          type: array
          items:
            $ref: '#/components/schemas/WalletPurchase'
          description: ''
        balance:
          type: string
          description: The wallet's new balance, as a decimal string.
  securitySchemes:
    BasicAuth:
      type: http
      description: The `username` is a Maxio Chargify API key. The `password` is `x`.
      scheme: basic
x-refined-from:
- maxio-advanced-billing-openapi31json.json
- maxio-advanced-billing-openapi.yml
x-provenance:
  method: harvested
  publisher: Maxio
  source: https://developers.maxio.com/static/exports/maxio-advanced-billing-openapi31json.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)