> ## Documentation Index > Fetch the complete documentation index at: https://docs.fungies.io/llms.txt > Use this file to discover all available pages before exploring further. # Charge Subscription > Charge an additional one-off amount to an active Subscription. Creates a new Invoice and handles payment processing. Multiple items (up to 20) can be charged in a single call; each becomes its own Invoice line. All items must share the same currency, and that currency must match the Subscription's currency. Tax is calculated on the total and distributed proportionally across the lines. ## OpenAPI ````yaml /api-reference/api-docs.yaml post /v0/subscriptions/{subscriptionIdOrNumber}/charge openapi: 3.1.0 info: title: Fungies API v0 version: 0.3.5 servers: - url: https://api.fungies.io security: [] tags: - name: discounts description: Discounts related endpoints - name: keys description: Offer product keys related endpoints - name: orders description: Orders related endpoints - name: payments description: Payments related endpoints - name: offers description: Offers related endpoints - name: products description: Products related endpoints - name: subscriptions description: Subscriptions related endpoints - name: users description: Users related endpoints - name: variants description: Product variants related endpoints - name: plans description: Product plans related endpoints - name: elements description: Elements related endpoints paths: /v0/subscriptions/{subscriptionIdOrNumber}/charge: post: tags: - subscriptions summary: Charge Subscription description: |- Charge an additional one-off amount to an active Subscription. Creates a new Invoice and handles payment processing. Multiple items (up to 20) can be charged in a single call; each becomes its own Invoice line. All items must share the same currency, and that currency must match the Subscription's currency. Tax is calculated on the total and distributed proportionally across the lines. operationId: PostV0SubscriptionsSubscriptionIdOrNumberCharge parameters: - name: subscriptionIdOrNumber in: path required: true description: Subscription ID or order number schema: $ref: >- #/components/schemas/PostV0SubscriptionsSubscriptionIdOrNumberChargeParameterSubscriptionIdOrNumber requestBody: description: POST /v0/subscriptions/:subscriptionIdOrNumber/charge Request body content: application/json: schema: $ref: >- #/components/schemas/PostV0SubscriptionsSubscriptionIdOrNumberChargeRequestBody responses: '200': description: >- POST /v0/subscriptions/:subscriptionIdOrNumber/charge Positive response content: application/json: schema: $ref: >- #/components/schemas/PostV0SubscriptionsSubscriptionIdOrNumberChargePositiveResponse '400': description: >- POST /v0/subscriptions/:subscriptionIdOrNumber/charge Negative response content: application/json: schema: $ref: >- #/components/schemas/PostV0SubscriptionsSubscriptionIdOrNumberChargeNegativeResponse examples: example1: value: status: error error: message: Sample error message security: - APIKEY_1: [] APIKEY_2: [] components: schemas: PostV0SubscriptionsSubscriptionIdOrNumberChargeParameterSubscriptionIdOrNumber: type: string pattern: ^#?([0-9A-Za-z]{12,32}|[0-9]+)(-[0-9]+)?$ description: Subscription ID or order number PostV0SubscriptionsSubscriptionIdOrNumberChargeRequestBody: type: object properties: description: type: string items: type: array items: type: object properties: name: type: string description: >- Name of the Item. Required if Offer ID is not provided. Can be used to override the Offer name. examples: - Premium Plan unitPrice: type: integer format: int64 exclusiveMinimum: 100 maximum: 9007199254740991 description: >- New unit price in cents (min: 100). Required if Offer ID is not provided. Can be used to override the Offer price. examples: - 10000 currency: type: string enum: - AFN - ALL - DZD - AOA - ARS - AMD - AWG - AUD - AZN - BSD - BDT - BBD - BZD - BMD - BOB - BAM - BWP - BRL - BHD - GBP - BND - BGN - BIF - BYN - KHR - CAD - CVE - KYD - KWD - XAF - XPF - CLP - CNY - COP - KMF - CDF - CRC - HRK - CZK - DKK - DJF - DOP - XCD - EGP - ETB - EUR - FKP - FJD - GMD - GEL - GIP - GTQ - GNF - GYD - HTG - HNL - HKD - HUF - ISK - INR - IDR - ILS - JMD - JPY - JOD - KZT - KES - KGS - LAK - LBP - LSL - LRD - MOP - MKD - MGA - MWK - MYR - MVR - MRO - MUR - MXN - MDL - MNT - MAD - MZN - MMK - NAD - NPR - ANG - TWD - NZD - NIO - NGN - NOK - OMR - PKR - PAB - PGK - PYG - PEN - PHP - PLN - QAR - RON - RUB - RWF - SHP - SVC - WST - STD - SAR - RSD - SCR - SLL - SGD - SBD - SOS - ZAR - KRW - LKR - SRD - SZL - SEK - CHF - TJS - TZS - THB - TND - TOP - TTD - TRY - UGX - UAH - AED - UYU - USD - UZS - VUV - VEF - VND - XOF - YER - ZMW - SLE - XCG - SSP - VES - MRU - STN - VED description: >- Valid currency code. Required if value is provided. Required if Offer ID is not provided. Can be used to override the Offer currency. Note: Currently needs to match Workspace currency. examples: - USD quantity: type: number format: double minimum: 1 maximum: 1.7976931348623157e+308 default: 1 description: 'Optional quantity (default: 1).' examples: - 1 offerId: type: string format: uuid description: |- Optional valid Offer ID. Adds Offer reference to the Item. Note: name, value and currency are derived from the Offer if not provided. - name: Offer name with full specification - value: Offer price - currency: Offer currency examples: - 123e4567-e89b-12d3-a456-426614174000 price: type: number format: double minimum: 100 maximum: 1.7976931348623157e+308 description: Deprecated. Use value instead. value: type: number format: double minimum: 100 maximum: 1.7976931348623157e+308 description: Deprecated. Use unitPrice instead. minItems: 1 maxItems: 20 required: - items PostV0SubscriptionsSubscriptionIdOrNumberChargePositiveResponse: type: object properties: status: type: string const: success data: type: object properties: payment: type: object properties: object: type: string enum: - payment default: payment description: >- Object type identifier. Always 'payment' for payment objects. id: type: string format: uuid description: Unique identifier (UUID) for this payment. type: type: string enum: - one_time - subscription_initial - subscription_update - subscription_interval - subscription_extra - claim_free description: |- Type of payment: - one_time: Single purchase - subscription_initial: First subscription payment - subscription_update: Subscription modification payment - subscription_interval: Recurring subscription payment - subscription_extra: Additional subscription charge - claim_free: Free product claim number: type: string pattern: ^#?([0-9A-Za-z]{12,32}|[0-9]+)(-[0-9]+)?$ description: >- Human-readable payment number (e.g., #ABC123DEF456). Used for reference in invoices and support. status: type: string enum: - PENDING - PAID - FAILED - UNPAID - CANCELLED - REFUNDED - PARTIALLY_REFUNDED - EXPIRED description: |- Current payment status: - PENDING: Being processed - PAID: Completed successfully - FAILED: Payment failed - UNPAID: Not yet attempted - CANCELLED: Was cancelled - REFUNDED: Fully refunded - PARTIALLY_REFUNDED: Partially refunded - EXPIRED: Expired before completion value: type: - integer - 'null' format: int64 minimum: -9007199254740991 maximum: 9007199254740991 default: 0 description: >- Payment amount in smallest currency unit (e.g., cents for USD). Includes tax but excludes fees. tax: type: - integer - 'null' format: int64 minimum: -9007199254740991 maximum: 9007199254740991 default: 0 description: >- Tax amount in smallest currency unit. Included in the total value. fee: type: - integer - 'null' format: int64 minimum: -9007199254740991 maximum: 9007199254740991 default: 0 description: >- Processing fee in smallest currency unit. This is deducted from your payout. currency: type: - string - 'null' enum: - AFN - ALL - DZD - AOA - ARS - AMD - AWG - AUD - AZN - BSD - BDT - BBD - BZD - BMD - BOB - BAM - BWP - BRL - BHD - GBP - BND - BGN - BIF - BYN - KHR - CAD - CVE - KYD - KWD - XAF - XPF - CLP - CNY - COP - KMF - CDF - CRC - HRK - CZK - DKK - DJF - DOP - XCD - EGP - ETB - EUR - FKP - FJD - GMD - GEL - GIP - GTQ - GNF - GYD - HTG - HNL - HKD - HUF - ISK - INR - IDR - ILS - JMD - JPY - JOD - KZT - KES - KGS - LAK - LBP - LSL - LRD - MOP - MKD - MGA - MWK - MYR - MVR - MRO - MUR - MXN - MDL - MNT - MAD - MZN - MMK - NAD - NPR - ANG - TWD - NZD - NIO - NGN - NOK - OMR - PKR - PAB - PGK - PYG - PEN - PHP - PLN - QAR - RON - RUB - RWF - SHP - SVC - WST - STD - SAR - RSD - SCR - SLL - SGD - SBD - SOS - ZAR - KRW - LKR - SRD - SZL - SEK - CHF - TJS - TZS - THB - TND - TOP - TTD - TRY - UGX - UAH - AED - UYU - USD - UZS - VUV - VEF - VND - XOF - YER - ZMW - SLE - XCG - SSP - VES - MRU - STN - VED default: null description: ISO 4217 currency code (e.g., USD, EUR, GBP). currencyDecimals: type: - integer - 'null' format: int64 minimum: -9007199254740991 maximum: 9007199254740991 default: null description: >- Number of decimal places for this currency (e.g., 2 for USD, 0 for JPY). createdAt: type: - integer - 'null' format: int64 minimum: 0 maximum: 9007199254740991 description: Unix timestamp (milliseconds) when the payment was created. userId: type: - string - 'null' format: uuid default: null description: >- UUID of the user who made this payment, if associated with a user account. user: type: - object - 'null' properties: object: type: string enum: - user default: user description: Object type identifier. Always 'user' for user objects. id: type: string format: uuid description: Unique identifier (UUID) for this user. username: type: - string - 'null' default: null description: Username of the user, if set. required: - id default: null description: Short user object with basic information about the payer. orderId: type: - string - 'null' format: uuid default: null description: >- UUID of the initial order, for subscription payments this links to the first order. orderNumber: type: - string - 'null' pattern: ^#?([0-9A-Za-z]{12,32}|[0-9]+)(-[0-9]+)?$ default: null description: Human-readable order number of the initial order. order: type: - object - 'null' properties: object: type: string enum: - order default: order description: >- Object type identifier. Always 'order' for order objects. id: type: string format: uuid description: Unique identifier (UUID) for this order. number: type: string pattern: ^#?([0-9A-Za-z]{12,32}|[0-9]+)(-[0-9]+)?$ description: Human-readable order number. status: type: string enum: - PENDING - PAID - FAILED - UNPAID - CANCELLED - REFUNDED - PARTIALLY_REFUNDED - EXPIRED description: Current order status. required: - id - number - status default: null description: >- Short order object with basic information about the associated order. subscriptionId: type: - string - 'null' pattern: ^#?([0-9A-Za-z]{12,32}|[0-9]+)(-[0-9]+)?$ default: null description: >- Subscription identifier if this is a subscription-related payment. subscription: type: - object - 'null' properties: object: type: string enum: - subscription default: subscription description: >- Object type identifier. Always 'subscription' for subscription objects. id: type: string pattern: ^#?([0-9A-Za-z]{12,32}|[0-9]+)(-[0-9]+)?$ description: Subscription identifier (based on initial order number). status: type: string enum: - all - active - canceled - incomplete - incomplete_expired - past_due - trialing - paused - unpaid description: |- Subscription status from payment provider: - active: Subscription is active and billing - past_due: Payment failed, retry in progress - canceled: Subscription has been cancelled - unpaid: Payment failed after all retries - incomplete: Initial payment pending - incomplete_expired: Initial payment expired - trialing: In trial period - paused: Subscription is paused required: - id - status default: null description: Short subscription object with status and ID. discount: type: - object - 'null' properties: object: type: string enum: - discount default: discount description: >- Object type identifier. Always 'discount' for discount objects. id: type: string format: uuid description: Unique identifier (UUID) for this discount. type: type: string enum: - code - sale description: >- Discount type: 'code' for coupon codes, 'sale' for automatic discounts. name: type: - string - 'null' default: null description: Display name of the discount. amount: type: number format: double minimum: -1.7976931348623157e+308 maximum: 1.7976931348623157e+308 description: >- Discount amount (fixed value in currency units or percentage value). amountType: type: string enum: - fixed - percentage description: >- Whether amount is 'fixed' (currency value) or 'percentage'. discountCode: type: - string - 'null' default: null description: The coupon code if this is a code-type discount. required: - id - type - amount - amountType default: null description: >- Applied discount details if a discount code or sale was used. invoiceNumber: type: - string - 'null' default: null description: >- Invoice number for completed payments. Only available for PAID, REFUNDED, or PARTIALLY_REFUNDED statuses. invoiceUrl: type: - string - 'null' default: null description: >- URL to download the invoice PDF. Only available for completed payments with generated invoices. charges: type: - array - 'null' items: type: object properties: object: type: string enum: - charge default: charge description: >- Object type identifier. Always 'charge' for charge objects. id: type: string format: uuid description: Unique identifier (UUID) for this charge. status: type: - string - 'null' enum: - succeeded - pending - failed default: null description: |- Charge status: - succeeded: Payment was successful - pending: Payment is being processed - failed: Payment attempt failed createdAt: type: - number - 'null' format: double minimum: -1.7976931348623157e+308 maximum: 1.7976931348623157e+308 default: null description: >- Unix timestamp (milliseconds) when the charge was created. ipAddress: type: - string - 'null' default: null description: >- IP address of the customer at time of charge, if available. paymentMethod: type: - object - 'null' properties: type: type: string description: >- Payment method type (e.g., card, paypal, bank_transfer, klarna, affirm). brand: type: - string - 'null' enum: - visa - mastercard - amex - discover - diners - jcb - unionpay default: null description: >- Card brand if payment method is a card (visa, mastercard, amex, discover, diners, jcb, unionpay). last4: type: - string - 'null' default: null description: Last 4 digits of the card or account number. card: type: object properties: brand: type: - string - 'null' enum: - visa - mastercard - amex - discover - diners - jcb - unionpay default: null last4: type: - string - 'null' default: null country: type: - string - 'null' network: type: - string - 'null' wallet: type: - object - 'null' properties: type: type: string enum: - amex_express_checkout - apple_pay - google_pay - link - masterpass - samsung_pay - visa_checkout description: >- The type of digital wallet used for the payment. Possible values: - amex_express_checkout: Amex Express Checkout - apple_pay: Apple Pay - google_pay: Google Pay - link: Stripe Link - masterpass: Masterpass - samsung_pay: Samsung Pay - visa_checkout: Visa Checkout dynamicLast4: type: - string - 'null' default: null description: >- The last four digits of the device account number. For Apple Pay, this is the last four digits of the Device Account Number. May differ from the physical card's last4. required: - type default: null description: >- Digital wallet details, if the card payment was made via a wallet (e.g., Apple Pay, Google Pay). Null when no wallet was used. description: >- Card-specific payment details. Present when the payment method type is 'card'. required: - type default: null description: Payment method details used for this charge. reason: type: - string - 'null' default: null description: >- Machine-readable failure reason code if the charge failed. sellerMessage: type: - string - 'null' default: null description: >- Human-readable message explaining the charge outcome, useful for failed charges. required: - id default: null description: >- Array of charge attempts for this payment. Each charge represents a payment attempt with status and payment method details. required: - id - type - number - status - createdAt required: - payment required: - status - data PostV0SubscriptionsSubscriptionIdOrNumberChargeNegativeResponse: type: object properties: status: type: string const: error error: type: object properties: message: type: string required: - message required: - status - error securitySchemes: APIKEY_1: type: apiKey in: header name: x-fngs-public-key APIKEY_2: type: apiKey in: header name: x-fngs-secret-key ````