> ## Documentation Index
> Fetch the complete documentation index at: https://developers.appstle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger immediate billing for an order

> Queues a billing attempt for immediate processing, bypassing the scheduled billing date. It works on an upcoming attempt (to bill it now) and on a failed one (to retry it).

**Asynchronous processing:**
- A `200` response with an empty body means the billing attempt was accepted: its `status` becomes `REQUESTING` and the charge is sent to Shopify shortly after. It does not contain the payment result
- A membership can't be billed twice within 24 hours (3 hours when it bills every day). If another attempt of the same membership was billed, failed or is due within 24 hours before or after the call, this attempt ends with status `SKIPPED` even though the call returned `200`: no order is created, and the attempt isn't billed on its scheduled date either

**Tracking the result:**
- Webhooks: `membership.billing-success` or `membership.billing-failure`
- Polling: `GET /api/external/v2/subscription-billing-attempts/past-orders?contractId={contractId}` and check the attempt `status`:
  - `REQUESTING` / `PROGRESS`: still processing
  - `SECURITY_CHALLENGE`: the card issuer requires 3D Secure
  - `SUCCESS` / `FAILURE`: final result
  - `SKIPPED`: no order was created
  - Any other status, such as `CONTRACT_PAUSED`, `CONTRACT_CANCELLED` or `SHOPIFY_EXCEPTION`: the attempt stopped; stop polling

**Important Notes:**
- The store's Appstle plan must include immediate orders. Without it, the call returns `400` with `errorKey` `feature_access_denied`
- Call it only for an upcoming or failed attempt: it doesn't refuse an attempt that has already succeeded
- A store may have a daily limit of 3 immediate orders, unless support has raised it, shared by API keys, partner tokens and **Attempt Billing** in the Appstle admin. Past it, the call returns `400` with `errorKey` `immediate_order_daily_limit_exceeded` until midnight UTC. A call counts even when it then fails, and so does a call the limit refuses, so don't retry a refused call the same day. See [Daily limit on immediate orders](https://developers.appstle.com/memberships/authentication#daily-limit-on-immediate-orders)
- Only an `ACTIVE` membership can be billed; any other status returns `400` with `errorKey` `contract_not_active`
- An attempt that is already `REQUESTING` or `PROGRESS` returns `400` with `errorKey` `billingInProgress`
- An unknown attempt ID, or one that belongs to another store, returns `400` with `errorKey` `invalidContract`
- Creates an actual order in Shopify and charges the customer's payment method
- Cannot be undone once processed

**Authentication:** Requires a valid `X-API-Key` header with a **Read & Write** key



## OpenAPI

````yaml /memberships/admin-api-swagger.json put /api/external/v2/subscription-billing-attempts/attempt-billing/{id}
openapi: 3.0.1
info:
  description: >-
    Comprehensive API documentation for managing memberships, payments, and
    related operations. These APIs allow you to programmatically manage
    membership lifecycles, handle payments, configure products, and integrate
    membership functionality into your applications.
  title: Admin APIs
  version: 0.0.1
servers:
  - url: https://membership-admin.appstle.com
security: []
tags:
  - description: >-
      APIs for retrieving product swap/substitution options allowing members to
      exchange membership items based on configured swap rules and variant
      groups
    name: Product Swap Rules
  - description: >-
      APIs for managing customer payment methods, payment tokens, and payment
      method retrieval for memberships
    name: Customer Payment Methods
  - description: >-
      APIs for managing one-time product additions to upcoming membership
      orders, including adding, retrieving, and removing one-off items
    name: One-Time Add-Ons
  - description: >-
      APIs for managing membership contracts including creation, updates, status
      changes, line items, discounts, and billing operations
    name: Membership Contracts
  - description: >-
      APIs for retrieving historical discount code usage and redemption
      information for membership contracts
    name: Customer Discount History
  - description: >-
      APIs for managing customer portal settings including UI customization,
      text labels, feature toggles, and branding options for the member
      self-service portal
    name: Customer Portal Configuration
  - description: >-
      APIs for retrieving custom CSS styles applied to membership widgets and
      customer portal for theme customization
    name: Custom CSS Styling
  - description: >-
      APIs for managing membership cancellation flow settings including
      retention offers, survey questions, and cancel confirmation screens
    name: Cancellation Flow Configuration
  - description: >-
      APIs for managing membership billing attempts, recurring orders, payment
      retries, order history, and order skipping
    name: Billing & Orders
  - description: >-
      APIs for managing Shopify delivery profiles, shipping rates, zones, and
      free shipping configuration for membership memberships
    name: Shipping & Delivery Profiles
  - description: >-
      APIs for managing membership plan groups, including creating plans,
      configuring discounts, billing intervals, and assigning products to plans
    name: Membership Plans
  - description: >-
      APIs for retrieving product catalog, variants, pricing, and inventory
      information for memberships.
    name: Product & Inventory Data
  - description: >-
      APIs for managing shop-level membership settings, configuration, and
      general store information.
    name: Shop Settings
  - description: >-
      APIs for performing bulk/mass operations on multiple membership contracts
      including status updates, product replacements, and billing date changes.
    name: Bulk Operations
paths:
  /api/external/v2/subscription-billing-attempts/attempt-billing/{id}:
    put:
      tags:
        - Billing & Orders
      summary: Trigger immediate billing for an order
      description: >-
        Queues a billing attempt for immediate processing, bypassing the
        scheduled billing date. It works on an upcoming attempt (to bill it now)
        and on a failed one (to retry it).


        **Asynchronous processing:**

        - A `200` response with an empty body means the billing attempt was
        accepted: its `status` becomes `REQUESTING` and the charge is sent to
        Shopify shortly after. It does not contain the payment result

        - A membership can't be billed twice within 24 hours (3 hours when it
        bills every day). If another attempt of the same membership was billed,
        failed or is due within 24 hours before or after the call, this attempt
        ends with status `SKIPPED` even though the call returned `200`: no order
        is created, and the attempt isn't billed on its scheduled date either


        **Tracking the result:**

        - Webhooks: `membership.billing-success` or `membership.billing-failure`

        - Polling: `GET
        /api/external/v2/subscription-billing-attempts/past-orders?contractId={contractId}`
        and check the attempt `status`:
          - `REQUESTING` / `PROGRESS`: still processing
          - `SECURITY_CHALLENGE`: the card issuer requires 3D Secure
          - `SUCCESS` / `FAILURE`: final result
          - `SKIPPED`: no order was created
          - Any other status, such as `CONTRACT_PAUSED`, `CONTRACT_CANCELLED` or `SHOPIFY_EXCEPTION`: the attempt stopped; stop polling

        **Important Notes:**

        - The store's Appstle plan must include immediate orders. Without it,
        the call returns `400` with `errorKey` `feature_access_denied`

        - Call it only for an upcoming or failed attempt: it doesn't refuse an
        attempt that has already succeeded

        - A store may have a daily limit of 3 immediate orders, unless support
        has raised it, shared by API keys, partner tokens and **Attempt
        Billing** in the Appstle admin. Past it, the call returns `400` with
        `errorKey` `immediate_order_daily_limit_exceeded` until midnight UTC. A
        call counts even when it then fails, and so does a call the limit
        refuses, so don't retry a refused call the same day. See [Daily limit on
        immediate
        orders](https://developers.appstle.com/memberships/authentication#daily-limit-on-immediate-orders)

        - Only an `ACTIVE` membership can be billed; any other status returns
        `400` with `errorKey` `contract_not_active`

        - An attempt that is already `REQUESTING` or `PROGRESS` returns `400`
        with `errorKey` `billingInProgress`

        - An unknown attempt ID, or one that belongs to another store, returns
        `400` with `errorKey` `invalidContract`

        - Creates an actual order in Shopify and charges the customer's payment
        method

        - Cannot be undone once processed


        **Authentication:** Requires a valid `X-API-Key` header with a **Read &
        Write** key
      operationId: attemptBillingV2
      parameters:
        - description: Billing attempt ID to retry
          example: 123456
          in: path
          name: id
          required: true
          schema:
            format: int64
            type: integer
        - description: API Key (Deprecated - Use Header X-API-Key instead)
          in: query
          name: api_key
          required: false
          schema:
            type: string
        - in: header
          name: X-API-Key
          required: false
          schema:
            type: string
      responses:
        '200':
          description: >-
            Billing attempt accepted for immediate processing. The body is empty
            and does not contain the payment result
        '400':
          description: >-
            Cannot bill now: the store's plan doesn't include immediate orders
            (`feature_access_denied`), the attempt doesn't exist
            (`invalidContract`), the membership isn't active
            (`contract_not_active`), the attempt is already in progress
            (`billingInProgress`), the store has reached its daily limit of
            immediate orders (`immediate_order_daily_limit_exceeded`), or the
            charge would exceed the store's charge cap
            (`billing_amount_escalation_blocked`)
        '401':
          description: Authentication required
        '403':
          description: The API key is read-only

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.