> ## Documentation Index > Fetch the complete documentation index at: https://docs.metrifox.com/llms.txt > Use this file to discover all available pages before exploring further. # Top up credits on a subscription > Create a one-time topup order that grants additional credits against an active subscription. The request body is the credit line items. ## OpenAPI ````yaml POST /api/v1/subscriptions/{subscription_id}/topup_credits openapi: 3.0.1 info: title: Metrifox API Documentation version: v1 description: >- Welcome to Metrifox Platform's API documentation. This comprehensive API suite enables seamless integration with our platform, providing secure and efficient access to our services. servers: - url: https://{defaultHost} variables: defaultHost: default: api.metrifox.com security: - api_key: [] paths: /api/v1/subscriptions/{subscription_id}/topup_credits: post: tags: - Subscriptions summary: Top up credits on a subscription description: > Creates a one-time topup order that grants additional credits against an active subscription. The destination subscription is identified entirely by the `{subscription_id}` path parameter. The customer and the order currency are derived from the subscription itself, so the request body is just the credit line items — one per credit you want to top up. Metrifox resolves the credit attachment, the one-time top-up price for the subscription's currency, and the destination wallet for each line item. You don't need to look up a `wallet_id` first. The endpoint creates a normal Metrifox order, generates an invoice for the total amount, and returns a `payment_intent` you can use to complete payment with your configured payment gateway. Once the payment succeeds, Metrifox provisions the new credit allocations on the corresponding wallets. **Requirements** - `{subscription_id}` must identify a subscription that exists for the current tenant and is in an `active` or `in_trial` state. - Each `credit_key` must be granted by the subscription's plan or addons, with `topup_enabled: true` on the credit attachment and a one-time topup price configured in the subscription's currency. - `quantity` must be at least the credit attachment's `min_purchase_quantity` (defaults to `1` when unset). Multiple line items are processed in a single order and roll into a single invoice. operationId: creditTopupSubscription parameters: - in: path name: subscription_id required: true schema: type: string description: >- The ID of the active subscription the credits should be granted against. example: 9c3a7180-3a05-4a7c-9b09-2ad1c9a2b8d1 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TopupOrderRequest' examples: single_topup: summary: Top up a single credit value: line_items: - credit_key: credit_tokens quantity: 100 multi_topup: summary: Top up multiple credits in one order value: line_items: - credit_key: credit_tokens quantity: 100 - credit_key: credit_storage_gb quantity: 50 responses: '201': description: Topup order created successfully content: application/json: schema: $ref: '#/components/schemas/TopupOrderResponse' examples: topup_created: summary: Topup order response value: statusCode: 201 message: Topup order created successfully meta: {} data: id: 5b1f12a4-7e1e-4d5c-8b7a-2c8a8a4c3a92 order_number: ORD-1042 customer_id: 764c80e3-ed59-44a5-ba07-7ee5ba547774 status: pending currency_code: USD subtotal_in_standard_unit: 100 discount_amount_in_standard_unit: 0 tax_amount_in_standard_unit: 0 total_in_standard_unit: 100 invoices: - id: 5e5d2f9a-4f4e-4f1d-8c9c-2f1c4e3b9a01 status: pending total_in_standard_unit: 100 payment_intent: id: pi_1Nxxxxx client_secret: pi_1Nxxxxx_secret_xxxxx should_collect_payment: true should_collect_card: false created_at: '2026-05-29T18:42:11Z' errors: {} '400': description: Bad request - validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: topup_not_available: summary: >- The subscription's plan does not grant this credit, or top-up is disabled on the attachment value: message: >- Top-up is not available for credit credit_tokens. Ensure the subscription's plan grants this credit and has top-up enabled. errors: {} no_topup_price_in_currency: summary: >- No one-time topup price configured in the subscription's currency value: message: >- No one-time topup price configured for credit credit_tokens in USD errors: {} invalid_quantity: summary: Quantity is below the credit attachment's minimum value: message: Quantity for credit credit_tokens must be at least 5 errors: {} '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Subscription not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: subscription_not_found: summary: >- subscription_id does not match an active subscription for this tenant value: message: >- Subscription 9c3a7180-3a05-4a7c-9b09-2ad1c9a2b8d1 not found or is not currently active errors: {} x-codeSamples: - lang: curl label: cURL source: > curl -X POST https://api.metrifox.com/api/v1/subscriptions/9c3a7180-3a05-4a7c-9b09-2ad1c9a2b8d1/topup_credits \ -H "x-api-key: $METRIFOX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "line_items": [ { "credit_key": "credit_tokens", "quantity": 100 } ] }' components: schemas: TopupOrderRequest: type: object required: - line_items properties: line_items: type: array minItems: 1 description: > One or more credits to top up on the subscription identified by the `{subscription_id}` path parameter. Each item creates one credit allocation on the corresponding wallet. items: $ref: '#/components/schemas/TopupOrderLineItem' TopupOrderResponse: type: object properties: statusCode: type: integer example: 201 message: type: string example: Topup order created successfully meta: type: object additionalProperties: true data: $ref: '#/components/schemas/TopupOrderEntity' errors: type: object additionalProperties: true ErrorResponse: type: object properties: message: type: string description: Error message errors: type: object additionalProperties: true description: Detailed error information TopupOrderLineItem: type: object required: - credit_key - quantity properties: credit_key: type: string description: > The `key` of the credit to top up (e.g. `credit_tokens`). The subscription identified by the `{subscription_id}` path parameter must grant this credit through its plan, with `topup_enabled: true` on the credit attachment and a one-time topup price configured in the subscription's currency. example: credit_tokens quantity: type: integer minimum: 1 description: >- Number of credit units to purchase. Must be at least the credit attachment's `min_purchase_quantity` (defaults to `1` when unset). example: 100 TopupOrderEntity: type: object description: >- A simplified view of the order returned from the topup endpoint. Additional order fields are present and forward-compatible. properties: id: type: string description: Unique order identifier order_number: type: string description: Human-readable order number customer_id: type: string description: ID of the customer on Metrifox status: type: string description: Order status (`pending`, `processing`, `completed`, etc.) currency_code: type: string description: ISO 4217 currency code for this order subtotal_in_standard_unit: type: number description: Subtotal in the order's currency discount_amount_in_standard_unit: type: number description: Total discount applied in the order's currency tax_amount_in_standard_unit: type: number description: Total tax in the order's currency total_in_standard_unit: type: number description: Final total to be charged in the order's currency invoices: type: array description: >- Invoices generated for this order. Topup orders typically generate exactly one invoice. items: $ref: '#/components/schemas/TopupOrderInvoice' should_collect_payment: type: boolean description: > Whether the order will be fulfilled only after payment is collected. When `true`, the order is held until payment succeeds and the credits are provisioned afterwards. When `false`, the order is fulfilled immediately regardless of payment. Topups are always in-advance, so this defaults to `true` based on the tenant's subscription settings. created_at: type: string format: date-time additionalProperties: true TopupOrderInvoice: type: object description: >- The invoice generated for the topup order. Use `payment_intent` to complete payment via your configured payment gateway. properties: id: type: string description: Invoice ID status: type: string description: Invoice status (e.g. `pending`, `paid`) total_in_standard_unit: type: number description: Invoice total in the order's currency payment_intent: type: object nullable: true additionalProperties: true description: >- Gateway-specific payment intent payload (e.g. Stripe `payment_intent`) the client uses to confirm payment. additionalProperties: true securitySchemes: api_key: type: apiKey name: x-api-key in: header ````