---
title: Create customer prepaid order by usage quota
slug: reference/create-customer-prepaid-order-by-usage-quota
docTags:
createdAt: 2025-03-18T18:28:02.918Z
---
{
"id": "XlEoqVqdRz6SZgTuMw1-8",
"type": "api-oas-v2",
"data": {
"method": "POST",
"url": "https://app.amberflo.io/payments/pricing/amberflo/customer-prepaid/usage",
"servers": [
{
"url": "https://app.amberflo.io/payments/pricing/amberflo/customer-prepaid/usage"
}
],
"name": "Create customer prepaid order by usage quota",
"description": "Creates a new prepaid credit order for a customer based on usage quotas rather than price amounts.\nThis allows customers to purchase specific amounts of service usage (API calls, storage, etc.) in advance.
\nUse this endpoint to:
\n\n- Purchase prepaid usage quotas for specific service dimensions
\n- Set up recurring prepaid usage subscriptions
\n- Provide customers with usage-based prepaid billing options
\n- Create bulk usage quota purchases for enterprise customers
\n
\nUsage Types:
\n\n- API Calls: Prepaid number of API requests
\n- Storage: Prepaid gigabytes or terabytes of storage
\n- Compute: Prepaid compute hours or processing units
\n- Bandwidth: Prepaid data transfer quotas
\n
",
"contentType": "application/json",
"request": {
"pathParameters": [],
"headerParameters": [],
"queryParameters": [],
"bodyDataParameters": [
{
"kind": "optional",
"name": "body",
"type": "object",
"description": "Prepaid usage order configuration including customer details, usage quotas, dimensions, and recurrence settings",
"customType": "payment.pricing.customer.CustomerPrepaidByUsage.in",
"schema": [
{
"name": "id",
"kind": "optional",
"type": "string",
"description": "Id of the new prepaid order.",
"example": ""
},
{
"name": "customerId",
"kind": "optional",
"type": "string",
"description": "`customerId` as defined in [Customer API](ref:post_customers).",
"example": ""
},
{
"name": "startTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp when the prepaid card should become active and available for use.",
"example": 0
},
{
"name": "endTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp when the prepaid card expires and becomes unavailable for further usage.",
"example": 0
},
{
"name": "firstCardEndTimeSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp when the first card in a recurring series expires, used for schedule calculations.",
"example": 0
},
{
"name": "productId",
"kind": "optional",
"type": "string",
"description": "Product ID as defined in account pricing. Change from default only if you have multiple products.",
"example": ""
},
{
"name": "prepaidOfferVersion",
"kind": "optional",
"type": "integer",
"description": "Can be -1 or the account level prepaid offer 'lastUpdateTimeInMillis' attribute value. The 'lastUpdateTimeInMillis' came to guarantee that the prepaid purchased by the customer has the exact same worth and expiration value as communicated to the customer prior to the actual transaction. If this field is set to -1 than there is no such guarantee, so if the account's prepaid offer was changed between the point the prepaid terms were communicated to the customer and the point of the actual purchase, then the server will use the new prepaid offer to calculate the worth of the prepaid and the expiration date (which might be different than what was communicated to the customer).",
"example": 0
},
{
"name": "prepaidPrice",
"kind": "optional",
"type": "number",
"description": "The amount to charge the customer for this prepaid order.",
"example": ""
},
{
"name": "originalWorth",
"kind": "optional",
"type": "number",
"description": "The locked-in monetary worth of the prepaid card to prevent value changes from offer updates.",
"example": ""
},
{
"name": "originalCurrency",
"kind": "optional",
"type": "string",
"description": "Currency code in ISO 4217 format for the original prepaid card worth.",
"example": "USD"
},
{
"name": "preferredPurchasingPrepaidCurrency",
"kind": "optional",
"type": "string",
"description": "Currency code in ISO 4217 format for preferred payment processing of this prepaid purchase.",
"example": "USD"
},
{
"name": "recurrenceFrequency",
"kind": "optional",
"type": "object",
"description": "Leave this field as null if you order a one prepaid.",
"modelRef": "#/components/schemas/payment.pricing.BillingPeriod.in",
"customType": "payment.pricing.BillingPeriod.in",
"schema": [
{
"name": "interval",
"kind": "optional",
"type": "string",
"description": "Time interval unit for billing cycle such as day, month, or year",
"modelRef": "#/components/schemas/payment.pricing.BillingPeriodInterval.in",
"customType": "payment.pricing.BillingPeriodInterval.in",
"schema": []
},
{
"name": "intervalsCount",
"kind": "optional",
"type": "integer",
"description": "Number of intervals in billing cycle with minimum value of 1",
"example": 0
}
]
},
{
"name": "externalPayment",
"kind": "optional",
"type": "boolean",
"description": "If true then the ordered prepaid card will be marked as external payment. Amberflo won't try to initiate a payment for the card. But instead wait for a signal from the account the card payment is settled.",
"example": ""
},
{
"name": "relationId",
"kind": "optional",
"type": "string",
"description": "Unique identifier for customer-prepaid relationship, computed as base64 of serialized JSON for external system integration.",
"example": ""
},
{
"name": "createdTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp when the prepaid order was originally created, separate from activation time.",
"example": 0
},
{
"name": "label",
"kind": "optional",
"type": "string",
"description": "Human-readable label for the prepaid order to help identify and organize prepaid cards.",
"example": ""
},
{
"name": "prepaidConditions",
"kind": "optional",
"type": "object",
"description": "",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.PrepaidConditions.in",
"customType": "payment.billing.prepaid_to_product.PrepaidConditions.in",
"schema": [
{
"name": "prepaidConditionsList",
"kind": "optional",
"type": "object",
"description": "Collection of active prepaid conditions determining when credits can be applied to invoices.",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.PrepaidCondition.in",
"customType": "payment.billing.prepaid_to_product.PrepaidCondition.in[]",
"schema": [],
"complexType": "oneOf",
"complexItems": [
{
"name": "payment.billing.prepaid_to_product.DimensionValueMapPrepaidCondition.in",
"description": "",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.DimensionValueMapPrepaidCondition.in",
"schema": [
{
"name": "type",
"kind": "optional",
"type": "string",
"description": "Type identifier for dimension-based prepaid condition, automatically set to class name.",
"example": "",
"default": "DimensionValueMapPrepaidCondition"
},
{
"name": "dimensionMapValue",
"kind": "optional",
"type": "map",
"description": "Single dimension key-value pair specifying usage dimension criteria for prepaid credit application.",
"example": "",
"customType": "map",
"schema": []
}
]
},
{
"name": "payment.billing.prepaid_to_product.ProductItemDimensionPrepaidCondition.in",
"description": "",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.ProductItemDimensionPrepaidCondition.in",
"schema": [
{
"name": "type",
"kind": "optional",
"type": "string",
"description": "Fixed type identifier for product item dimension prepaid condition implementation",
"example": "",
"default": "ProductItemDimensionPrepaidCondition"
},
{
"name": "productItemId",
"kind": "optional",
"type": "string",
"description": "Unique identifier of product item where prepaid credits should be applied",
"example": ""
},
{
"name": "dimensions",
"kind": "optional",
"type": "map",
"description": "Optional dimension key-value pairs for targeted credit application within product item",
"example": "",
"customType": "map",
"schema": []
}
]
},
{
"name": "payment.billing.prepaid_to_product.ProductItemPrepaidCondition.in",
"description": "",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.ProductItemPrepaidCondition.in",
"schema": [
{
"name": "type",
"kind": "optional",
"type": "string",
"description": "Fixed type identifier for product item prepaid condition implementation",
"example": "",
"default": "ProductItemPrepaidCondition"
},
{
"name": "productItemId",
"kind": "optional",
"type": "string",
"description": "Unique identifier of product item where all prepaid credits should be applied",
"example": ""
}
]
}
]
},
{
"name": "prepaidConditionsHistory",
"kind": "optional",
"type": "map",
"description": "Historical record of prepaid conditions keyed by timestamp for audit tracking.",
"example": "",
"customType": "map",
"schema": []
}
]
},
{
"name": "commitmentId",
"kind": "optional",
"type": "string",
"description": "Optional commitment contract identifier populated by internal processes for contract-based prepaid cards.",
"example": ""
},
{
"name": "orderId",
"kind": "optional",
"type": "string",
"description": "Optional order identifier populated by internal processes for tracking prepaid purchases.",
"example": ""
},
{
"name": "orderItemId",
"kind": "optional",
"type": "string",
"description": "Optional order line item identifier populated by internal processes for detailed order tracking.",
"example": ""
},
{
"name": "senderPrepaidUri",
"kind": "optional",
"type": "string",
"description": "Optional prepaid card URI that was used to transfer funds into this prepaid card.",
"example": ""
},
{
"name": "customPriority",
"kind": "optional",
"type": "number",
"description": "an optional field to indicate the priority of the prepaid. When using the prepaid cards, cards with higher priority will be used before cards with lower priority.",
"example": ""
},
{
"name": "prepaidPriority",
"kind": "optional",
"type": "string",
"description": "Priority level for prepaid card usage order with automatic calculation algorithms for highest or lowest positions.",
"modelRef": "#/components/schemas/payment.pricing.prepaid.PrepaidPriority.in",
"customType": "payment.pricing.prepaid.PrepaidPriority.in",
"schema": []
},
{
"name": "startAtMidCycle",
"kind": "optional",
"type": "boolean",
"description": "Whether this prepaid card should be applied immediately as an ad-hoc mid-cycle addition.",
"example": ""
},
{
"name": "realTimePricing",
"kind": "optional",
"type": "boolean",
"description": "Whether to use real-time pricing calculations for this prepaid card's value and billing.",
"example": ""
},
{
"name": "installments",
"kind": "optional",
"type": "object",
"description": "The payment installments for the prepaid card.",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.PrepaidInstallments.in",
"customType": "payment.billing.prepaid_to_product.PrepaidInstallments.in",
"schema": [
{
"name": "prepaidInstallments",
"kind": "required",
"type": "array",
"description": "Ordered list of payment schedules defining when installments are billed to customer",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.PrepaidInstallmentSchedule.in",
"customType": "payment.billing.prepaid_to_product.PrepaidInstallmentSchedule.in[]",
"schema": [
{
"name": "amountPrice",
"kind": "required",
"type": "number",
"description": "Payment amount of individual installment charged to customer in account base currency",
"example": ""
},
{
"name": "scheduledPurchaseTimeInSeconds",
"kind": "required",
"type": "integer",
"description": "Unix timestamp when installment payment should be processed and billed to customer",
"example": 0
}
]
}
]
},
{
"name": "type",
"kind": "optional",
"type": "string",
"description": "Discriminator field that identifies this as a usage-based prepaid card order request.",
"example": "",
"default": "customer_prepaid_by_usage"
},
{
"name": "purchaseType",
"kind": "optional",
"type": "string",
"description": "Prepaid card purchase model defining whether credits are allocated by fixed price or usage amount",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.PrepaidPurchaseType.in",
"customType": "payment.billing.prepaid_to_product.PrepaidPurchaseType.in",
"schema": []
},
{
"name": "prepaidUsage",
"kind": "optional",
"type": "number",
"description": "The specific quantity of usage units to pre-purchase for this prepaid card.",
"example": ""
},
{
"name": "prepaidFullPrice",
"kind": "optional",
"type": "number",
"description": "The full price of the usage when the card was created, used to create ad-hoc discounts by comparing against actual prepaidPrice.",
"example": ""
}
],
"modelRef": "#/components/schemas/payment.pricing.customer.CustomerPrepaidByUsage.in",
"isExpanded": true
}
],
"formDataParameters": [],
"oAuthParameters": [
{
"id": "apiKey",
"name": "X-API-KEY",
"kind": "optional",
"type": "apiKey",
"in": "header"
}
]
},
"responses": [
{
"statusCode": "200",
"description": "Successfully created usage-based prepaid order and returns detailed quota information with usage terms",
"jsonExample": "",
"isExpanded": true,
"schema": [
{
"kind": "optional",
"type": "object",
"description": "Detailed customer prepaid credit information with either price-based or usage-based billing structure and transaction history.",
"customType": "payment.pricing.customer.detailed.DetailedCustomerPrepaid.out",
"schema": [],
"modelRef": "#/components/schemas/payment.pricing.customer.detailed.DetailedCustomerPrepaid.out",
"complexItems": [
{
"name": "object",
"schema": [
{
"name": "id",
"kind": "optional",
"type": "string",
"description": "Unique identifier for the prepaid order, used for tracking and referencing throughout the system.",
"example": ""
},
{
"name": "customerId",
"kind": "optional",
"type": "string",
"description": "Customer identifier as defined in Customer API, required for prepaid card assignment.",
"example": ""
},
{
"name": "startTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp when the prepaid card becomes active and available for use, must be positive.",
"example": 0
},
{
"name": "endTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp when the prepaid card expires and becomes unavailable for further usage.",
"example": 0
},
{
"name": "firstCardEndTimeSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp when the first card in a recurring series expires, used for schedule calculations.",
"example": 0
},
{
"name": "productId",
"kind": "optional",
"type": "string",
"description": "Product identifier as defined in account pricing configuration, change from default only for multi-product accounts.",
"example": ""
},
{
"name": "prepaidOfferVersion",
"kind": "optional",
"type": "integer",
"description": "Prepaid offer version timestamp ensuring consistent pricing between quote and purchase, or -1 for current version.",
"example": 0
},
{
"name": "prepaidPrice",
"kind": "optional",
"type": "number",
"description": "Amount of prepaid money ordered in credit units or base currency, must be non-negative value.",
"example": ""
},
{
"name": "originalWorth",
"kind": "optional",
"type": "number",
"description": "Locked-in monetary worth of the prepaid card to prevent value changes from future offer updates.",
"example": ""
},
{
"name": "originalCurrency",
"kind": "optional",
"type": "string",
"description": "Currency code in ISO 4217 format.",
"example": "USD"
},
{
"name": "preferredPurchasingPrepaidCurrency",
"kind": "optional",
"type": "string",
"description": "Currency code in ISO 4217 format.",
"example": "USD"
},
{
"name": "recurrenceFrequency",
"kind": "optional",
"type": "object",
"description": "Billing period for recurring prepaid cards, null for one-time purchases only.",
"modelRef": "#/components/schemas/payment.pricing.BillingPeriod.out",
"customType": "payment.pricing.BillingPeriod.out",
"schema": [
{
"name": "interval",
"kind": "optional",
"type": "string",
"description": "Time interval unit for billing cycle such as day, month, or year",
"modelRef": "#/components/schemas/payment.pricing.BillingPeriodInterval.in",
"customType": "payment.pricing.BillingPeriodInterval.in",
"schema": []
},
{
"name": "intervalsCount",
"kind": "optional",
"type": "integer",
"description": "Number of intervals in billing cycle with minimum value of 1",
"example": 0
}
]
},
{
"name": "externalPayment",
"kind": "optional",
"type": "boolean",
"description": "Flag indicating external payment processing where Amberflo invoices but waits for external payment confirmation.",
"example": ""
},
{
"name": "relationId",
"kind": "optional",
"type": "string",
"description": "Unique base64-encoded identifier for customer-prepaid relationship, computed automatically for external system integration.",
"example": ""
},
{
"name": "createdTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp when the prepaid order was originally created, separate from activation time.",
"example": 0
},
{
"name": "label",
"kind": "optional",
"type": "string",
"description": "Human-readable label for the prepaid order to help identify and organize prepaid cards.",
"example": ""
},
{
"name": "prepaidConditions",
"kind": "optional",
"type": "object",
"description": "Conditions defining how and when the prepaid card can be applied to product usage.",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.PrepaidConditions.out",
"customType": "payment.billing.prepaid_to_product.PrepaidConditions.out",
"schema": [
{
"name": "prepaidConditionsList",
"kind": "optional",
"type": "object",
"description": "Active set of prepaid conditions determining when credits apply to customer charges",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.PrepaidCondition.out",
"customType": "payment.billing.prepaid_to_product.PrepaidCondition.out[]",
"schema": [],
"complexType": "oneOf",
"complexItems": [
{
"name": "payment.billing.prepaid_to_product.DimensionValueMapPrepaidCondition.in",
"description": "",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.DimensionValueMapPrepaidCondition.in",
"schema": [
{
"name": "type",
"kind": "optional",
"type": "string",
"description": "Type identifier for dimension-based prepaid condition, automatically set to class name.",
"example": "",
"default": "DimensionValueMapPrepaidCondition"
},
{
"name": "dimensionMapValue",
"kind": "optional",
"type": "map",
"description": "Single dimension key-value pair specifying usage dimension criteria for prepaid credit application.",
"example": "",
"customType": "map",
"schema": []
}
]
},
{
"name": "payment.billing.prepaid_to_product.ProductItemDimensionPrepaidCondition.in",
"description": "",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.ProductItemDimensionPrepaidCondition.in",
"schema": [
{
"name": "type",
"kind": "optional",
"type": "string",
"description": "Fixed type identifier for product item dimension prepaid condition implementation",
"example": "",
"default": "ProductItemDimensionPrepaidCondition"
},
{
"name": "productItemId",
"kind": "optional",
"type": "string",
"description": "Unique identifier of product item where prepaid credits should be applied",
"example": ""
},
{
"name": "dimensions",
"kind": "optional",
"type": "map",
"description": "Optional dimension key-value pairs for targeted credit application within product item",
"example": "",
"customType": "map",
"schema": []
}
]
},
{
"name": "payment.billing.prepaid_to_product.ProductItemPrepaidCondition.in",
"description": "",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.ProductItemPrepaidCondition.in",
"schema": [
{
"name": "type",
"kind": "optional",
"type": "string",
"description": "Fixed type identifier for product item prepaid condition implementation",
"example": "",
"default": "ProductItemPrepaidCondition"
},
{
"name": "productItemId",
"kind": "optional",
"type": "string",
"description": "Unique identifier of product item where all prepaid credits should be applied",
"example": ""
}
]
}
]
},
{
"name": "prepaidConditionsHistory",
"kind": "optional",
"type": "map",
"description": "Historical timeline mapping timestamps to condition sets for audit and tracking purposes",
"example": "",
"customType": "map",
"schema": []
}
]
},
{
"name": "commitmentId",
"kind": "optional",
"type": "string",
"description": "Optional commitment contract identifier populated by internal processes for contract-based prepaid cards.",
"example": ""
},
{
"name": "orderId",
"kind": "optional",
"type": "string",
"description": "Optional order identifier populated by internal processes for tracking prepaid purchases.",
"example": ""
},
{
"name": "orderItemId",
"kind": "optional",
"type": "string",
"description": "Optional order line item identifier populated by internal processes for detailed order tracking.",
"example": ""
},
{
"name": "senderPrepaidUri",
"kind": "optional",
"type": "string",
"description": "Optional prepaid card URI that was used to transfer funds into this prepaid card.",
"example": ""
},
{
"name": "customPriority",
"kind": "optional",
"type": "number",
"description": "Optional priority value for prepaid card usage order, higher priority cards are used before lower priority cards.",
"example": ""
},
{
"name": "prepaidPriority",
"kind": "optional",
"type": "string",
"description": "Standard priority classification for prepaid card usage ordering and selection algorithms.",
"modelRef": "#/components/schemas/payment.pricing.prepaid.PrepaidPriority.in",
"customType": "payment.pricing.prepaid.PrepaidPriority.in",
"schema": []
},
{
"name": "startAtMidCycle",
"kind": "optional",
"type": "boolean",
"description": "Flag indicating whether this prepaid card should be applied immediately as an ad-hoc mid-cycle addition.",
"example": ""
},
{
"name": "realTimePricing",
"kind": "optional",
"type": "boolean",
"description": "Flag indicating whether to use real-time pricing calculations for this prepaid card's value and billing.",
"example": ""
},
{
"name": "installments",
"kind": "optional",
"type": "object",
"description": "The payment installments for the prepaid card.",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.PrepaidInstallments.out",
"customType": "payment.billing.prepaid_to_product.PrepaidInstallments.out",
"schema": [
{
"name": "prepaidInstallments",
"kind": "required",
"type": "array",
"description": "Ordered list of payment schedules defining when installments are billed to customer",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.PrepaidInstallmentSchedule.in",
"customType": "payment.billing.prepaid_to_product.PrepaidInstallmentSchedule.in[]",
"schema": [
{
"name": "amountPrice",
"kind": "required",
"type": "number",
"description": "Payment amount of individual installment charged to customer in account base currency",
"example": ""
},
{
"name": "scheduledPurchaseTimeInSeconds",
"kind": "required",
"type": "integer",
"description": "Unix timestamp when installment payment should be processed and billed to customer",
"example": 0
}
]
}
]
},
{
"name": "internalStatus",
"kind": "optional",
"type": "string",
"description": "Internal processing status of the prepaid card for system tracking and workflow management.",
"example": ""
},
{
"name": "prepaidPaymentTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp when the prepaid card payment was effectively settled, only set for settled payments.",
"example": 0
},
{
"name": "paymentId",
"kind": "optional",
"type": "string",
"description": "Unique identifier for the payment transaction associated with this prepaid card purchase.",
"example": ""
},
{
"name": "paymentStatus",
"kind": "optional",
"type": "string",
"description": "Current status of the payment transaction for this prepaid card indicating processing state.",
"modelRef": "#/components/schemas/payment.payment.PaymentStatus.in",
"customType": "payment.payment.PaymentStatus.in",
"schema": []
},
{
"name": "firstInvoiceUri",
"kind": "optional",
"type": "string",
"description": "URI reference to the first invoice generated for this prepaid card purchase.",
"example": ""
},
{
"name": "modifiedTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp when the prepaid card record was last modified for external system integration tracking.",
"example": 0
},
{
"name": "type",
"kind": "optional",
"type": "string",
"description": "Discriminator field identifying this as a detailed price-based prepaid card, automatically set.",
"example": "",
"default": "detailed_customer_prepaid_by_price"
},
{
"name": "purchaseType",
"kind": "optional",
"type": "string",
"description": "Purchase type classification automatically set to PREPAID_BY_PRICE for this price-based variant.",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.PrepaidPurchaseType.in",
"customType": "payment.billing.prepaid_to_product.PrepaidPurchaseType.in",
"schema": []
},
{
"name": "actualPrepaidChargePrice",
"kind": "optional",
"type": "number",
"description": "The actual absolute charge amount for the prepaid card, in base currency.",
"example": ""
}
],
"modelRef": "#/components/schemas/payment.pricing.customer.detailed.DetailedCustomerPrepaidByPrice.out",
"customType": "payment.pricing.customer.detailed.DetailedCustomerPrepaidByPrice.out"
},
{
"name": "object",
"schema": [
{
"name": "id",
"kind": "optional",
"type": "string",
"description": "Unique identifier for the prepaid card purchase order.",
"example": ""
},
{
"name": "customerId",
"kind": "optional",
"type": "string",
"description": "Customer identifier who purchased this prepaid card.",
"example": ""
},
{
"name": "startTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp when the prepaid card becomes active for usage.",
"example": 0
},
{
"name": "endTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp when the prepaid card expires and stops providing credits.",
"example": 0
},
{
"name": "firstCardEndTimeSeconds",
"kind": "optional",
"type": "integer",
"description": "End time of the first card for recurring prepaid subscriptions.",
"example": 0
},
{
"name": "productId",
"kind": "optional",
"type": "string",
"description": "Product identifier this prepaid card applies to for usage credits.",
"example": ""
},
{
"name": "prepaidOfferVersion",
"kind": "optional",
"type": "integer",
"description": "Version number of the prepaid offer configuration used for this purchase.",
"example": 0
},
{
"name": "prepaidPrice",
"kind": "optional",
"type": "number",
"description": "Actual price paid for this prepaid usage card in account currency.",
"example": ""
},
{
"name": "originalWorth",
"kind": "optional",
"type": "number",
"description": "Original monetary value of the prepaid card before any discounts applied.",
"example": ""
},
{
"name": "originalCurrency",
"kind": "optional",
"type": "string",
"description": "Currency code in ISO 4217 format.",
"example": "USD"
},
{
"name": "preferredPurchasingPrepaidCurrency",
"kind": "optional",
"type": "string",
"description": "Preferred currency for purchasing prepaid cards in ISO 4217 format.",
"example": "USD"
},
{
"name": "recurrenceFrequency",
"kind": "optional",
"type": "object",
"description": "Leave this field as null if you order a one prepaid.",
"modelRef": "#/components/schemas/payment.pricing.BillingPeriod.out",
"customType": "payment.pricing.BillingPeriod.out",
"schema": [
{
"name": "interval",
"kind": "optional",
"type": "string",
"description": "Time interval unit for billing cycle such as day, month, or year",
"modelRef": "#/components/schemas/payment.pricing.BillingPeriodInterval.in",
"customType": "payment.pricing.BillingPeriodInterval.in",
"schema": []
},
{
"name": "intervalsCount",
"kind": "optional",
"type": "integer",
"description": "Number of intervals in billing cycle with minimum value of 1",
"example": 0
}
]
},
{
"name": "externalPayment",
"kind": "optional",
"type": "boolean",
"description": "Indicates if payment was processed outside the standard payment system.",
"example": ""
},
{
"name": "relationId",
"kind": "optional",
"type": "string",
"description": "Identifier linking this prepaid card to related entities or transactions.",
"example": ""
},
{
"name": "createdTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp when this prepaid card order was initially created.",
"example": 0
},
{
"name": "label",
"kind": "optional",
"type": "string",
"description": "Optional descriptive label for identifying this prepaid card purchase.",
"example": ""
},
{
"name": "prepaidConditions",
"kind": "optional",
"type": "object",
"description": "Collection manager for prepaid conditions with historical tracking for credit application rules",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.PrepaidConditions.out",
"customType": "payment.billing.prepaid_to_product.PrepaidConditions.out",
"schema": [
{
"name": "prepaidConditionsList",
"kind": "optional",
"type": "object",
"description": "Active set of prepaid conditions determining when credits apply to customer charges",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.PrepaidCondition.out",
"customType": "payment.billing.prepaid_to_product.PrepaidCondition.out[]",
"schema": [],
"complexType": "oneOf",
"complexItems": [
{
"name": "payment.billing.prepaid_to_product.DimensionValueMapPrepaidCondition.in",
"description": "",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.DimensionValueMapPrepaidCondition.in",
"schema": [
{
"name": "type",
"kind": "optional",
"type": "string",
"description": "Type identifier for dimension-based prepaid condition, automatically set to class name.",
"example": "",
"default": "DimensionValueMapPrepaidCondition"
},
{
"name": "dimensionMapValue",
"kind": "optional",
"type": "map",
"description": "Single dimension key-value pair specifying usage dimension criteria for prepaid credit application.",
"example": "",
"customType": "map",
"schema": []
}
]
},
{
"name": "payment.billing.prepaid_to_product.ProductItemDimensionPrepaidCondition.in",
"description": "",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.ProductItemDimensionPrepaidCondition.in",
"schema": [
{
"name": "type",
"kind": "optional",
"type": "string",
"description": "Fixed type identifier for product item dimension prepaid condition implementation",
"example": "",
"default": "ProductItemDimensionPrepaidCondition"
},
{
"name": "productItemId",
"kind": "optional",
"type": "string",
"description": "Unique identifier of product item where prepaid credits should be applied",
"example": ""
},
{
"name": "dimensions",
"kind": "optional",
"type": "map",
"description": "Optional dimension key-value pairs for targeted credit application within product item",
"example": "",
"customType": "map",
"schema": []
}
]
},
{
"name": "payment.billing.prepaid_to_product.ProductItemPrepaidCondition.in",
"description": "",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.ProductItemPrepaidCondition.in",
"schema": [
{
"name": "type",
"kind": "optional",
"type": "string",
"description": "Fixed type identifier for product item prepaid condition implementation",
"example": "",
"default": "ProductItemPrepaidCondition"
},
{
"name": "productItemId",
"kind": "optional",
"type": "string",
"description": "Unique identifier of product item where all prepaid credits should be applied",
"example": ""
}
]
}
]
},
{
"name": "prepaidConditionsHistory",
"kind": "optional",
"type": "map",
"description": "Historical timeline mapping timestamps to condition sets for audit and tracking purposes",
"example": "",
"customType": "map",
"schema": []
}
]
},
{
"name": "commitmentId",
"kind": "optional",
"type": "string",
"description": "Associated commitment contract identifier if card was purchased under commitment terms.",
"example": ""
},
{
"name": "orderId",
"kind": "optional",
"type": "string",
"description": "Order identifier if this prepaid card was part of a larger order.",
"example": ""
},
{
"name": "orderItemId",
"kind": "optional",
"type": "string",
"description": "Specific line item identifier within an order for this prepaid purchase.",
"example": ""
},
{
"name": "senderPrepaidUri",
"kind": "optional",
"type": "string",
"description": "URI of the source prepaid card if this was created from splitting.",
"example": ""
},
{
"name": "customPriority",
"kind": "optional",
"type": "number",
"description": "Custom priority value for determining prepaid card consumption order.",
"example": ""
},
{
"name": "prepaidPriority",
"kind": "optional",
"type": "string",
"description": "Priority level for prepaid card usage order with automatic calculation algorithms for highest or lowest positions.",
"modelRef": "#/components/schemas/payment.pricing.prepaid.PrepaidPriority.in",
"customType": "payment.pricing.prepaid.PrepaidPriority.in",
"schema": []
},
{
"name": "startAtMidCycle",
"kind": "optional",
"type": "boolean",
"description": "Indicates if this prepaid card can be activated mid-billing cycle.",
"example": ""
},
{
"name": "realTimePricing",
"kind": "optional",
"type": "boolean",
"description": "Indicates if real-time pricing calculations apply to this prepaid card.",
"example": ""
},
{
"name": "installments",
"kind": "optional",
"type": "object",
"description": "The payment installments for the prepaid card.",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.PrepaidInstallments.out",
"customType": "payment.billing.prepaid_to_product.PrepaidInstallments.out",
"schema": [
{
"name": "prepaidInstallments",
"kind": "required",
"type": "array",
"description": "Ordered list of payment schedules defining when installments are billed to customer",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.PrepaidInstallmentSchedule.in",
"customType": "payment.billing.prepaid_to_product.PrepaidInstallmentSchedule.in[]",
"schema": [
{
"name": "amountPrice",
"kind": "required",
"type": "number",
"description": "Payment amount of individual installment charged to customer in account base currency",
"example": ""
},
{
"name": "scheduledPurchaseTimeInSeconds",
"kind": "required",
"type": "integer",
"description": "Unix timestamp when installment payment should be processed and billed to customer",
"example": 0
}
]
}
]
},
{
"name": "internalStatus",
"kind": "optional",
"type": "string",
"description": "Internal processing status for tracking prepaid card payment lifecycle.",
"example": ""
},
{
"name": "prepaidPaymentTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp when payment was successfully settled for this prepaid card.",
"example": 0
},
{
"name": "paymentId",
"kind": "optional",
"type": "string",
"description": "Payment transaction identifier for the prepaid card purchase.",
"example": ""
},
{
"name": "paymentStatus",
"kind": "optional",
"type": "string",
"description": "Payment processing status indicating current stage from pre-payment through settlement or failure",
"modelRef": "#/components/schemas/payment.payment.PaymentStatus.in",
"customType": "payment.payment.PaymentStatus.in",
"schema": []
},
{
"name": "firstInvoiceUri",
"kind": "optional",
"type": "string",
"description": "URI of the first invoice generated for this prepaid card purchase.",
"example": ""
},
{
"name": "modifiedTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp of last modification for external system integration tracking.",
"example": 0
},
{
"name": "type",
"kind": "optional",
"type": "string",
"description": "Type of template, automatically populated.",
"example": "",
"default": "detailed_customer_prepaid_by_usage"
},
{
"name": "purchaseType",
"kind": "optional",
"type": "string",
"description": "Prepaid card purchase model defining whether credits are allocated by fixed price or usage amount",
"modelRef": "#/components/schemas/payment.billing.prepaid_to_product.PrepaidPurchaseType.in",
"customType": "payment.billing.prepaid_to_product.PrepaidPurchaseType.in",
"schema": []
},
{
"name": "prepaidUsage",
"kind": "optional",
"type": "number",
"description": "Amount of usage units purchased with this prepaid card.",
"example": ""
},
{
"name": "prepaidFullPrice",
"kind": "optional",
"type": "number",
"description": "Full price of usage before any prepaid discounts were applied.",
"example": ""
}
],
"modelRef": "#/components/schemas/payment.pricing.customer.detailed.DetailedCustomerPrepaidByUsage.out",
"customType": "payment.pricing.customer.detailed.DetailedCustomerPrepaidByUsage.out"
}
],
"complexType": "oneOf",
"isExpanded": true
}
]
},
{
"statusCode": "400",
"description": "Invalid usage quota configuration, unsupported usage dimensions, or malformed request body",
"jsonExample": "",
"isExpanded": true
},
{
"statusCode": "401",
"description": "Authentication required or invalid API key provided",
"jsonExample": "",
"isExpanded": true
},
{
"statusCode": "403",
"description": "Insufficient permissions to create customer usage-based prepaid orders",
"jsonExample": "",
"isExpanded": true
},
{
"statusCode": "404",
"description": "Customer not found or usage-based prepaid service not configured for account",
"jsonExample": "",
"isExpanded": true
},
{
"statusCode": "409",
"description": "Conflicting usage quota order or dimension configuration issues",
"jsonExample": "",
"isExpanded": true
},
{
"statusCode": "500",
"description": "Internal server error occurred while creating usage-based prepaid order",
"jsonExample": "",
"isExpanded": true
}
],
"hasXCodeSamples": false,
"examples": {
"languages": [
{
"id": "6iycDCpXMrWQ-LbcDmUk0",
"language": "curl",
"label": "cURL",
"code": "curl --request POST \\\n --url https://app.amberflo.io/payments/pricing/amberflo/customer-prepaid/usage \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '{\n \"installments\": {\n \"prepaidInstallments\": [\n {\n \"amountPrice\": \"\",\n \"scheduledPurchaseTimeInSeconds\": 0\n }\n ]\n },\n \"type\": \"customer_prepaid_by_usage\"\n }'"
},
{
"id": "mQ0GYAog2M564vfjpUedl",
"language": "javascript",
"label": "javascript",
"code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar raw = JSON.stringify({\n \"installments\": {\n \"prepaidInstallments\": [\n {\n \"amountPrice\": \"\",\n \"scheduledPurchaseTimeInSeconds\": 0\n }\n ]\n },\n \"type\": \"customer_prepaid_by_usage\"\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://app.amberflo.io/payments/pricing/amberflo/customer-prepaid/usage\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));"
},
{
"id": "AU5aidWNQ0swp5M_yoBs4",
"language": "ruby",
"label": "Ruby",
"code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://app.amberflo.io/payments/pricing/amberflo/customer-prepaid/usage\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest.body = JSON.dump({\n \"installments\": {\n \"prepaidInstallments\": [\n {\n \"amountPrice\": \"\",\n \"scheduledPurchaseTimeInSeconds\": 0\n }\n ]\n },\n \"type\": \"customer_prepaid_by_usage\"\n})\n\nresponse = https.request(request)\nputs response.read_body\n"
},
{
"id": "bswq140dWN1j9Qqr7iTvV",
"language": "python",
"label": "Python",
"code": "import requests\nimport json\n\nurl = \"https://app.amberflo.io/payments/pricing/amberflo/customer-prepaid/usage\"\n\npayload = json.dumps({\n \"installments\": {\n \"prepaidInstallments\": [\n {\n \"amountPrice\": \"\",\n \"scheduledPurchaseTimeInSeconds\": 0\n }\n ]\n },\n \"type\": \"customer_prepaid_by_usage\"\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n"
}
],
"selectedLanguageId": "6iycDCpXMrWQ-LbcDmUk0"
},
"results": {
"languages": [
{
"id": "uAhURJr0wLBb2XZ_UhEaK",
"language": "200",
"code": "// Successfully created usage-based prepaid order and returns detailed quota information with usage terms\n{}"
},
{
"id": "_XFAWzPGtrp_txGvmJvCP",
"language": "400",
"code": "// Invalid usage quota configuration, unsupported usage dimensions, or malformed request body\n"
},
{
"id": "_y0hrxnr0R79DMEX52ITz",
"language": "401",
"code": "// Authentication required or invalid API key provided\n"
},
{
"id": "fw6WTkcbFyvXWTu0hBSnC",
"language": "403",
"code": "// Insufficient permissions to create customer usage-based prepaid orders\n"
},
{
"id": "36OXPZChUONBgCGgfvU0R",
"language": "404",
"code": "// Customer not found or usage-based prepaid service not configured for account\n"
},
{
"id": "nWbXH0DtV5lbe9OF5Q0Jk",
"language": "409",
"code": "// Conflicting usage quota order or dimension configuration issues\n"
},
{
"id": "7WBE4p0KTLrT63AQWrrpo",
"language": "500",
"code": "// Internal server error occurred while creating usage-based prepaid order\n"
}
],
"selectedLanguageId": "uAhURJr0wLBb2XZ_UhEaK"
}
},
"children": [
{
"text": ""
}
]
}