{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://artifacts.apis.io/recurly/json-schema/recurly-recovery-invoice-create-schema.json", "title": "RecoveryInvoiceCreate", "x-generated": "2026-11-05", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/recurly-recover-openapi.yml#/components/schemas/RecoveryInvoiceCreate", "type": "object", "properties": { "currency": { "type": "string", "title": "Currency", "description": "3-letter ISO 4217 currency code.", "maxLength": 3 }, "due_at": { "type": "string", "format": "date-time", "title": "Due at", "description": "Date invoice was originally due. Must be in the past." }, "po_number": { "type": "string", "title": "Purchase order number", "description": "This identifies the PO number associated with the subscription.", "maxLength": 50 }, "external_recovery_eligible": { "type": "boolean", "title": "External recovery eligible", "description": "Must be set to `true` to acknowledge that the invoice is eligible for external recovery. Requests with `false`, omitted, or non-boolean values will be rejected." }, "account": { "$ref": "#/$defs/RecoveryAccountCreate" }, "line_items": { "type": "array", "title": "Line items", "description": "Line items to include on the invoice. Currency is specified at the root level and must not be included in individual line items.", "items": { "$ref": "#/$defs/RecoveryLineItemCreate" } }, "transaction_descriptor_suffix": { "type": "string", "title": "Transaction Descriptor Suffix", "maxLength": 255, "description": "Optionally overrides the suffix component of the composed transaction descriptor. If omitted, the suffix is derived from the subscription's plan name or the invoice description, with a Trial prefix on Visa trial conversions. Subject to gateway availability and payment method support." } }, "required": [ "currency", "due_at", "external_recovery_eligible", "account", "line_items" ], "$defs": { "CustomField": { "type": "object", "title": "Custom field", "properties": { "name": { "type": "string", "title": "Field name", "description": "Fields must be created in the UI before values can be assigned to them.", "pattern": "/^[a-z0-9_-]+$/i", "maxLength": 50 }, "value": { "type": "string", "title": "Field value", "description": "Any values that resemble a credit card number or security code (CVV/CVC) will be rejected.", "maxLength": 255 }, "source_record_type": { "type": "string", "title": "Source record type", "description": "The type of record a custom field was automatically copied from.", "readOnly": true, "enum": [ "account", "plan", "product", "subscription" ] }, "source_record_id": { "type": "string", "title": "Source record ID", "description": "The UUID of the record this custom field was automatically copied from. Only present when the field was copied from another record.", "readOnly": true } }, "required": [ "name", "value" ] }, "CustomFields": { "type": "array", "title": "Custom fields", "description": "The custom fields will only be altered when they are included in a request. Sending an empty array will not remove any existing values. To remove a field send the name with a null or empty value.", "items": { "$ref": "#/$defs/CustomField" } }, "PaymentGatewayReferences": { "type": "object", "title": "Payment Gateway References Object", "description": "Array of Payment Gateway References, each a reference to a third-party gateway object of varying types.", "properties": { "token": { "type": "string", "title": "Token", "description": "Reference value used when the external token was created. If a Stripe gateway or Ebanx gateway is used, this value will need to be accompanied by its reference_type." }, "reference_type": { "type": "string", "title": "Reference Type", "description": "The type of reference token. The value can be omitted for gateways that only support one type of token.", "enum": [ "stripe_confirmation_token", "upi_vpa" ] } } }, "RecoveryAccountCreate": { "type": "object", "properties": { "address": { "$ref": "#/$defs/RecoveryAddress" }, "billing_infos": { "type": "array", "title": "Billing Infos", "description": "If the premium Wallet feature is enabled, more than one payment method can be associated with an account, and one can be designated as a primary and one as a backup. Without the Wallet feature, only one payment method will be accepted.", "items": { "$ref": "#/$defs/RecoveryBillingInfoCreate" } }, "code": { "type": "string", "description": "The unique identifier of the account. This cannot be changed once the account is created.", "maxLength": 50 }, "email": { "type": "string", "format": "email", "description": "The email address used for communicating with this customer.", "maxLength": 255 }, "custom_fields": { "$ref": "#/$defs/CustomFields" }, "dunning_campaign_id": { "type": "string", "title": "Dunning Campaign ID", "description": "Unique ID to identify a dunning campaign. Used to specify if a non-default dunning campaign should be assigned to this account. For sites without multiple dunning campaigns enabled, the default dunning campaign will always be used." } }, "required": [ "code", "billing_infos" ] }, "RecoveryAddress": { "type": "object", "properties": { "phone": { "type": "string", "title": "Phone number" }, "street1": { "type": "string", "title": "Street 1", "maxLength": 50 }, "street2": { "type": "string", "title": "Street 2", "maxLength": 50 }, "city": { "type": "string", "title": "City" }, "region": { "type": "string", "title": "State/Province", "description": "State or province." }, "postal_code": { "type": "string", "title": "Zip/Postal code", "description": "Zip or postal code." }, "country": { "type": "string", "title": "Country", "description": "Country, 2-letter ISO 3166-1 alpha-2 code." } } }, "RecoveryBillingInfoCreate": { "type": "object", "title": "Recovery billing info", "properties": { "first_name": { "type": "string", "title": "First name", "maxLength": 50 }, "last_name": { "type": "string", "title": "Last name", "maxLength": 50 }, "company": { "type": "string", "title": "Company name", "maxLength": 100 }, "address": { "$ref": "#/$defs/RecoveryAddress" }, "ip_address": { "type": "string", "title": "IP address", "description": "*STRONGLY RECOMMENDED* Customer's IP address when updating their billing information.", "maxLength": 20 }, "gateway_code": { "type": "string", "title": "An identifier for a specific payment gateway.", "description": "Required unless `number` is supplied — a full PAN is not constrained to a\nspecific gateway, so `gateway_code` is optional in that case. Depending on\ndunning campaign configuration, `gateway_code` may be required even when\n`number` is supplied, since the recovery transaction is attributed to a\nspecific gateway.\n", "maxLength": 12 }, "number": { "type": "string", "title": "Credit card number", "description": "Full card number (PAN). Spaces and dashes are accepted. When supplied,\n`month`, `year` and `network_transaction_id` are required, and\n`payment_method` is not accepted.\n" }, "month": { "type": "string", "title": "Expiration month", "description": "Required when `number` is supplied.", "maxLength": 2 }, "year": { "type": "string", "title": "Expiration year", "description": "Required when `number` is supplied.", "maxLength": 4 }, "primary_payment_method": { "type": "boolean", "title": "Primary Payment Method", "description": "The `primary_payment_method` field is used to designate the primary billing info on the account. An account can have a maximum of 1 primary. If a user sets a different payment method as a primary, then the existing primary will no longer be marked as such." }, "backup_payment_method": { "type": "boolean", "description": "The `backup_payment_method` field is used to designate a billing info as a backup on the account that will be tried if the initial billing info used for an invoice is declined. All payment methods, including the billing info marked `primary_payment_method` can be set as a backup. An account can have a maximum of 1 backup, if a user sets a different payment method as a backup, the existing backup will no longer be marked as such." }, "payment_gateway_references": { "type": "array", "description": "Array of Payment Gateway References, each a reference to a third-party\ngateway object of varying types. Cannot be combined with `number`.\n", "items": { "$ref": "#/$defs/PaymentGatewayReferences" } }, "payment_method": { "$ref": "#/$defs/RecoveryPaymentMethodCreate", "description": "Merchant-supplied fallback payment method metadata. Recurly's own gateway-token lookup is authoritative and will override any of these fields it can determine itself; these fields are only used to fill gaps when that lookup is unavailable. Not accepted when `number` is supplied." }, "network_transaction_id": { "type": "string", "title": "Network Transaction ID", "description": "Network transaction ID from the previous customer-in-session subscription signup or billing info storage. Required when `number` is supplied.\n\n- 10-15 alphanumeric characters for Mastercard\n- 14-15 alphanumeric for Visa\n- 15 digits for all other brands\n- 16 alphanumeric characters for Cartes Bancaires, which are processed as Visa or Mastercard\n", "maxLength": 16 }, "transactions": { "type": "array", "title": "Transactions", "description": "Transactions from previous collection attempts for this payment method. Optional, unless this billing_info is the primary payment method and the account's dunning campaign skips Recurly's own retry attempts entirely -- in that case at least one entry is required.", "items": { "$ref": "#/$defs/RecoveryTransactionCreate" } } } }, "RecoveryLineItemCreate": { "required": [ "unit_amount" ], "type": "object", "title": "Recovery line item", "properties": { "tax": { "type": "number", "format": "float", "title": "Tax", "description": "The tax amount for the line item." }, "custom_fields": { "$ref": "#/$defs/CustomFields" }, "harmonized_system_code": { "type": "string", "title": "Harmonized System Code", "description": "The Harmonized System (HS) code is an internationally standardized system of names and numbers to classify traded products. The HS code, sometimes called Commodity Code, is used by customs authorities around the world to identify products when assessing duties and taxes. The HS code may also be referred to as the tariff code or customs code. Values should contain only digits and decimals.", "maxLength": 25, "pattern": "^\\d+(\\.\\d+)*$" }, "product_code": { "type": "string", "title": "Product code", "description": "Optional field to track a product code or SKU for the line item. This can be used to later reporting on product purchases.", "maxLength": 50 }, "quantity": { "type": "integer", "title": "Quantity", "description": "This number will be multiplied by the unit amount to compute the subtotal before any discounts or taxes.", "default": 1 }, "description": { "type": "string", "title": "Description", "description": "Description that appears on the invoice.", "maxLength": 255 }, "unit_amount": { "type": "number", "format": "float", "title": "Unit amount", "description": "A positive or negative amount will result in a positive `unit_amount`." } } }, "RecoveryPaymentMethodCreate": { "type": "object", "title": "Recovery payment method", "description": "Merchant-supplied fallback for payment method metadata on the revenue recovery\nendpoint. Recurly's own gateway-token lookup is authoritative for these fields;\na value supplied here is only used to fill a gap when that lookup is restricted\nor fails, and is overwritten if that lookup later succeeds.\n\nNot accepted on the Purchase endpoint or the standard billing_info/billing_infos\nendpoints — Recover only.\n", "properties": { "object": { "description": "The payment method type.", "type": "string", "enum": [ "credit_card", "apple_pay", "google_pay", "google_pay_device_pan", "paypal_billing_agreement" ] }, "card_type": { "description": "The card brand (e.g. `Visa`, `MasterCard`). Present for `credit_card`, `apple_pay`, and `google_pay`/`google_pay_device_pan`; omitted for `paypal_billing_agreement`.", "type": "string", "enum": [ "American Express", "Dankort", "Diners Club", "Discover", "ELO", "Forbrugsforeningen", "Hipercard", "JCB", "Laser", "Maestro", "MasterCard", "Test Card", "Union Pay", "Unknown", "Visa", "Tarjeta Naranja" ] }, "first_six": { "type": "string", "description": "For a plain card, the card's own first six digits (BIN).\n\nFor a tokenized wallet payment (`apple_pay`, `google_pay`, or\n`google_pay_device_pan`), this is the DPAN's (the wallet/device token's own\nnumber) first six digits — **not** the underlying card's (FPAN). The FPAN is\nnever accepted or represented; no separate wallet-specific field is provided.\n", "maxLength": 6 }, "last_four": { "type": "string", "description": "The card's (or, for a tokenized wallet payment, the DPAN's) last four digits. See `first_six` for the DPAN-vs-FPAN distinction on wallets.", "maxLength": 4 }, "exp_month": { "type": "integer", "description": "Expiration month.", "maxLength": 2 }, "exp_year": { "type": "integer", "description": "Expiration year.", "maxLength": 4 } } }, "RecoveryTransactionCreate": { "required": [ "gateway_error_code", "attempted_collection_date" ], "type": "object", "properties": { "gateway_error_code": { "type": "string", "title": "Gateway error code", "description": "The error code returned by the payment gateway for the original payment collection attempt.", "maxLength": 50 }, "merchant_advice_code": { "type": "string", "title": "Merchant advice code", "description": "The advice code returned by the payment gateway for the original payment collection attempt. This field is only applicable for certain gateways.", "maxLength": 2 }, "attempted_collection_date": { "type": "string", "format": "date-time", "title": "Attempted collection date", "description": "The date the original payment collection was attempted." } } } } }