{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://artifacts.apis.io/recurly/json-schema/recurly-purchase-create-schema.json", "title": "PurchaseCreate", "description": "A purchase is only a request data type and is not persistent in Recurly, an InvoiceCollection will be the returned type.", "x-generated": "2026-11-05", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/recurly-openapi.yml#/components/schemas/PurchaseCreate", "type": "object", "properties": { "currency": { "type": "string", "title": "Currency", "description": "3-letter ISO 4217 currency code.", "maxLength": 3 }, "account": { "$ref": "#/$defs/AccountPurchase" }, "billing_info_id": { "type": "string", "description": "The `billing_info_id` is the value that represents a specific billing info for an end customer. When `billing_info_id` is used to assign billing info to the subscription, all future billing events for the subscription will bill to the specified billing info. `billing_info_id` can ONLY be used for sites utilizing the Wallet feature." }, "business_entity_id": { "type": "string", "title": "Business Entity ID", "description": "The `business_entity_id` is the value that represents a specific business entity for an end customer. When `business_entity_id` is used to assign a business entity to the subscription, all future billing events for the subscription will bill to the specified business entity. Available when the `Multiple Business Entities` feature is enabled. If both `business_entity_id` and `business_entity_code` are present, `business_entity_id` will be used." }, "business_entity_code": { "type": "string", "title": "Business Entity Code", "description": "The `business_entity_code` is the value that represents a specific business entity for an end customer. When `business_entity_code` is used to assign a business entity to the subscription, all future billing events for the subscription will bill to the specified business entity. Available when the `Multiple Business Entities` feature is enabled. If both `business_entity_id` and `business_entity_code` are present, `business_entity_id` will be used." }, "collection_method": { "title": "Collection method", "description": "Must be set to manual in order to preview a purchase for an Account that does not have payment information associated with the Billing Info.", "default": "automatic", "$ref": "#/$defs/CollectionMethodEnum" }, "po_number": { "type": "string", "title": "Purchase order number", "description": "For manual invoicing, this identifies the PO number associated with the subscription.", "maxLength": 50 }, "net_terms": { "type": "integer", "title": "Net terms", "description": "Integer paired with `Net Terms Type` and representing the number\nof days past the current date (for `net` Net Terms Type) or days after\nthe last day of the current month (for `eom` Net Terms Type) that the\ninvoice will become past due. For `manual` collection method, an additional 24 hours is\nadded to ensure the customer has the entire last day to make payment before\nbecoming past due. For example:\n\nIf an invoice is due `net 0`, it is due 'On Receipt' and will become past due 24 hours after it's created.\nIf an invoice is due `net 30`, it will become past due at 31 days exactly.\nIf an invoice is due `eom 30`, it will become past due 31 days from the last day of the current month.\n\nFor `automatic` collection method, the additional 24 hours is not added. For example, On-Receipt is due immediately, and `net 30` will become due exactly 30 days from invoice generation, at which point Recurly will attempt collection.\nWhen `eom` Net Terms Type is passed, the value for `Net Terms` is restricted to `0, 15, 30, 45, 60, or 90`.\n\nFor more information on how net terms work with `manual` collection visit our docs page (https://docs.recurly.com/docs/manual-payments#section-collection-terms)\nor visit (https://docs.recurly.com/docs/automatic-invoicing-terms#section-collection-terms) for information about net terms using `automatic` collection.", "minimum": 0, "default": 0 }, "net_terms_type": { "$ref": "#/$defs/NetTermsTypeEnum" }, "credit_application_policy_override": { "$ref": "#/$defs/CreditApplicationPolicy" }, "terms_and_conditions": { "type": "string", "title": "Terms and conditions", "description": "Terms and conditions to be put on the purchase invoice." }, "transaction": { "type": "object", "description": "(Transaction Data, Card on File) - Options for flagging transactions as Customer or Merchant Initiated Unscheduled.", "allOf": [ { "type": "object", "properties": { "initiator": { "$ref": "#/$defs/initiator" }, "merchant_reason_code": { "$ref": "#/$defs/merchant_reason_code" }, "skip_gateway_fraud": { "type": "boolean", "title": "Skip Gateway Fraud", "description": "When set to `true`, instructs the payment gateway to skip fraud checks for this transaction. This is useful for recurring transactions where fraud checks have already been performed on the initial transaction. Note that not all gateways support this feature. For Stripe, this skips Radar fraud rules; for Adyen, this skips" }, "skip_recurly_fraud": { "type": "boolean", "title": "Skip Recurly Fraud", "description": "When set to `true`, skips Recurly's fraud detection checks for this transaction, including Kount and IP-based fraud screening. Does not affect gateway-level fraud checks. Use `skip_all_fraud` to skip all fraud checks." }, "skip_all_fraud": { "type": "boolean", "title": "Skip All Fraud", "description": "When set to `true`, skips all fraud checks for this transaction, including both gateway-level fraud checks and Recurly's fraud detection services. This is useful for trusted transactions where fraud screening is not required." }, "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." } } } ] }, "customer_notes": { "type": "string", "title": "Customer notes" }, "vat_reverse_charge_notes": { "type": "string", "title": "VAT reverse charge notes", "description": "VAT reverse charge notes for cross border European tax settlement." }, "vertex_transaction_type": { "$ref": "#/$defs/VertexTransactionTypeEnum" }, "credit_customer_notes": { "type": "string", "title": "Credit customer notes", "description": "Notes to be put on the credit invoice resulting from credits in the purchase, if any." }, "gateway_code": { "type": "string", "title": "Gateway Code", "description": "The default payment gateway identifier to be used for the purchase transaction. This will also be applied as the default for any subscriptions included in the purchase request.", "maxLength": 13 }, "shipping": { "type": "object", "x-class-name": "ShippingPurchase", "properties": { "address_id": { "type": "string", "title": "Shipping address ID", "description": "Assign a shipping address from the account's existing shipping addresses. If this and `address` are both present, `address` will take precedence.", "maxLength": 13 }, "address": { "$ref": "#/$defs/ShippingAddressCreate" }, "fees": { "type": "array", "title": "Shipping fees", "description": "A list of shipping fees to be created as charges with the purchase.", "items": { "$ref": "#/$defs/ShippingFeeCreate" } } } }, "line_items": { "type": "array", "title": "Line items", "description": "A list of one time charges or credits to be created with the purchase.", "items": { "$ref": "#/$defs/LineItemCreate" } }, "subscriptions": { "type": "array", "title": "Subscriptions", "description": "A list of subscriptions to be created with the purchase.", "items": { "$ref": "#/$defs/SubscriptionPurchase" } }, "coupon_codes": { "type": "array", "title": "Coupon codes", "description": "A list of coupon_codes to be redeemed on the subscription or account during the purchase.", "items": { "type": "string" } }, "gift_card_redemption_code": { "type": "string", "title": "Gift card redemption code", "description": "A gift card redemption code to be redeemed on the purchase invoice." }, "transaction_type": { "description": "An optional type designation for the payment gateway transaction created by this request. Supports 'moto' value, which is the acronym for mail order and telephone transactions.", "$ref": "#/$defs/GatewayTransactionTypeEnum" } }, "required": [ "currency", "account" ], "$defs": { "AccountAcquisitionUpdate": { "type": "object", "properties": { "cost": { "type": "object", "x-class-name": "AccountAcquisitionCost", "title": "Account balance", "items": { "type": "object" }, "properties": { "currency": { "type": "string", "title": "Currency", "description": "3-letter ISO 4217 currency code.", "maxLength": 3 }, "amount": { "type": "number", "format": "float", "title": "Amount", "description": "The amount of the corresponding currency used to acquire the account." } } }, "channel": { "description": "The channel through which the account was acquired.", "$ref": "#/$defs/ChannelEnum" }, "subchannel": { "type": "string", "description": "An arbitrary subchannel string representing a distinction/subcategory within a broader channel." }, "campaign": { "type": "string", "description": "An arbitrary identifier for the marketing campaign that led to the acquisition of this account." }, "acquired_at": { "type": "string", "format": "date-time", "description": "Date the account was first created if different than the account.created_at. ie Importing accounts." } } }, "AccountPurchase": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Optional, but if present allows an existing account to be used and updated as part of the purchase.", "maxLength": 13 }, "code": { "type": "string", "description": "The unique identifier of the account. This cannot be changed once the account is created.", "maxLength": 50 }, "acquisition": { "$ref": "#/$defs/AccountAcquisitionUpdate" } }, "required": [ "code" ] }, { "$ref": "#/$defs/AccountUpdate" } ] }, "AccountUpdate": { "type": "object", "properties": { "username": { "type": "string", "description": "A secondary value for the account.", "maxLength": 255 }, "email": { "type": "string", "format": "email", "description": "The email address used for communicating with this customer. The customer will also use this email address to log into your hosted account management pages. This value does not need to be unique.", "maxLength": 255 }, "preferred_locale": { "description": "Used to determine the language and locale of emails sent on behalf of the merchant to the customer. The list of locales is restricted to those the merchant has enabled on the site.", "$ref": "#/$defs/PreferredLocaleEnum" }, "preferred_time_zone": { "type": "string", "description": "Used to determine the time zone of emails sent on behalf of the merchant to the customer. Must be a [supported IANA time zone name](https://docs.recurly.com/docs/email-time-zones-and-time-stamps#supported-api-iana-time-zone-names)" }, "cc_emails": { "type": "string", "description": "Additional email address that should receive account correspondence. These should be separated only by commas. These CC emails will receive all emails that the `email` field also receives.", "maxLength": 255 }, "first_name": { "type": "string", "maxLength": 255 }, "last_name": { "type": "string", "maxLength": 255 }, "company": { "type": "string", "maxLength": 100 }, "vat_number": { "type": "string", "description": "The VAT number of the account (to avoid having the VAT applied). This is only used for manually collected invoices.", "maxLength": 20 }, "tax_exempt": { "type": "boolean", "description": "The tax status of the account. `true` exempts tax on the account, `false` applies tax on the account." }, "exemption_certificate": { "type": "string", "description": "The tax exemption certificate number for the account. If the merchant has an integration for the Vertex tax provider, this optional value will be sent in any tax calculation requests for the account.", "maxLength": 30 }, "override_business_entity_id": { "type": "string", "title": "Override Business Entity ID", "description": "Unique ID to identify the business entity assigned to the account. Available when the `Multiple Business Entities` feature is enabled." }, "parent_account_code": { "type": "string", "maxLength": 50, "description": "The account code of the parent account to be associated with this account. Passing an empty value removes any existing parent association from this account. If both `parent_account_code` and `parent_account_id` are passed, the non-blank value in `parent_account_id` will be used. Only one level of parent child relationship is allowed. You cannot assign a parent account that itself has a parent account." }, "parent_account_id": { "type": "string", "maxLength": 13, "description": "The UUID of the parent account to be associated with this account. Passing an empty value removes any existing parent association from this account. If both `parent_account_code` and `parent_account_id` are passed, the non-blank value in `parent_account_id` will be used. Only one level of parent child relationship is allowed. You cannot assign a parent account that itself has a parent account." }, "bill_to": { "maxLength": 6, "description": "An enumerable describing the billing behavior of the account, specifically whether the account is self-paying or will rely on the parent account to pay.", "$ref": "#/$defs/BillToEnum" }, "transaction_type": { "description": "An optional type designation for the payment gateway transaction created by this request. Supports 'moto' value, which is the acronym for mail order and telephone transactions.", "$ref": "#/$defs/GatewayTransactionTypeEnum" }, "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." }, "invoice_template_id": { "type": "string", "title": "Invoice Template ID", "description": "Unique ID to identify an invoice template. Available when the site is on a Pro or Elite plan. Used to specify which invoice template, if any, should be used to generate invoices for the account." }, "address": { "$ref": "#/$defs/Address" }, "billing_info": { "$ref": "#/$defs/BillingInfoCreate" }, "custom_fields": { "$ref": "#/$defs/CustomFields" }, "entity_use_code": { "type": "string", "description": "The Avalara AvaTax value that can be passed to identify the customer type for tax purposes. The range of values can be A - R (more info at Avalara). Value is case-sensitive." }, "bill_date": { "type": "string", "title": "Bill Date", "format": "date-time", "description": "The preferred billing date for the account. This date will be used as the billing date for when activating new subscriptions on the account." } } }, "AchAccountTypeEnum": { "type": "string", "description": "The bank account type. (ACH only)", "enum": [ "checking", "savings" ] }, "AchTypeEnum": { "type": "string", "description": "The payment method type for a non-credit card based billing info. `bacs`, `becs`, `pix-automatico`, `mercadopago`, `upi-autopay` are the only accepted values.", "enum": [ "bacs", "becs", "pix-automatico", "mercadopago", "upi-autopay" ] }, "AddOnSourceEnum": { "type": "string", "title": "Add-on source", "description": "Used to determine where the associated add-on data is pulled from. If this value is set to\n`plan_add_on` or left blank, then add-on data will be pulled from the plan's add-ons. If the associated\n`plan` has `allow_any_item_on_subscriptions` set to `true` and this field is set to `item`, then\nthe associated add-on data will be pulled from the site's item catalog.\n", "default": "plan_add_on", "enum": [ "plan_add_on", "item" ] }, "Address": { "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." }, "geo_code": { "type": "string", "maxLength": 20, "description": "Code that represents a geographic entity (location or object). Only returned when Vertex or Avalara for Communications is enabled." } } }, "BillToEnum": { "type": "string", "enum": [ "parent", "self" ] }, "BillingInfoCreate": { "type": "object", "properties": { "token_id": { "type": "string", "title": "Token ID", "description": "A token [generated by Recurly.js](https://recurly.com/developers/reference/recurly-js/#getting-a-token).", "maxLength": 22 }, "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/Address" }, "number": { "type": "string", "title": "Credit card number", "description": "Credit card number, spaces and dashes are accepted." }, "month": { "type": "string", "title": "Expiration month", "maxLength": 2 }, "year": { "type": "string", "title": "Expiration year", "maxLength": 4 }, "cvv": { "type": "string", "title": "Security code or CVV", "description": "*STRONGLY RECOMMENDED*", "maxLength": 4 }, "currency": { "type": "string", "description": "3-letter ISO 4217 currency code." }, "vat_number": { "type": "string", "title": "VAT number" }, "ip_address": { "type": "string", "title": "IP address", "description": "*STRONGLY RECOMMENDED* Customer's IP address when updating their billing information.", "maxLength": 20 }, "gateway_token": { "type": "string", "title": "A token used in place of a credit card in order to perform transactions. Must be used in conjunction with `gateway_code`.", "maxLength": 50 }, "gateway_code": { "type": "string", "title": "An identifier for a specific payment gateway.", "maxLength": 12 }, "backup_gateway_code": { "type": "string", "title": "Identifies a backup gateway. Applies only when `gateway_code` is provided and that gateway is in failover. Providing this code overrides gateway exclusion configurations and restricts the backup to this gateway.", "maxLength": 12 }, "payment_gateway_references": { "type": "array", "description": "Array of Payment Gateway References, each a reference to a third-party gateway object of varying types.", "items": { "$ref": "#/$defs/PaymentGatewayReferences" }, "properties": { "token": { "type": "string", "maxLength": 50 }, "reference_type": { "type": "string", "$ref": "#/$defs/PaymentGatewayReferencesEnum" } } }, "gateway_attributes": { "type": "object", "description": "Additional attributes to send to the gateway.", "x-class-name": "GatewayAttributes", "properties": { "account_reference": { "type": "string", "description": "Used by Adyen and Braintree gateways. For Adyen the Shopper Reference value used when the external token was created. Must be used in conjunction with gateway_token and gateway_code. For Braintree the PayPal PayerID is populated in the response.", "maxLength": 264 } } }, "amazon_billing_agreement_id": { "type": "string", "title": "Amazon billing agreement ID", "description": "Only supported on Amazon V1. For Amazon V2, use token_id with Recurly.js." }, "paypal_billing_agreement_id": { "type": "string", "title": "PayPal billing agreement ID" }, "roku_billing_agreement_id": { "type": "string", "title": "Roku's CIB if billing through Roku" }, "fraud_session_id": { "type": "string", "title": "Fraud Session ID" }, "adyen_risk_profile_reference_id": { "type": "string", "title": "Adyen Risk Profile Reference ID", "description": "The Adyen Risk Profile Reference ID is used to identify the risk profile for the payment method." }, "transaction_type": { "description": "An optional type designation for the payment gateway transaction created by this request. Supports 'moto' value, which is the acronym for mail order and telephone transactions.", "$ref": "#/$defs/GatewayTransactionTypeEnum" }, "three_d_secure_action_result_token_id": { "type": "string", "title": "3-D Secure action result token ID", "description": "A token generated by Recurly.js after completing a 3-D Secure device fingerprinting or authentication challenge.", "maxLength": 22 }, "iban": { "type": "string", "maxLength": 34, "description": "The International Bank Account Number, up to 34 alphanumeric characters comprising a country code; two check digits; and a number that includes the domestic bank account number, branch identifier, and potential routing information" }, "name_on_account": { "type": "string", "maxLength": 255, "description": "The name associated with the bank account (ACH, SEPA, Bacs only)" }, "account_number": { "type": "string", "maxLength": 255, "description": "The bank account number. (ACH, Bacs only)" }, "routing_number": { "type": "string", "maxLength": 15, "description": "The bank's rounting number. (ACH only)" }, "sort_code": { "type": "string", "maxLength": 15, "description": "Bank identifier code for UK based banks. Required for Bacs based billing infos. (Bacs only)" }, "type": { "$ref": "#/$defs/AchTypeEnum" }, "account_type": { "$ref": "#/$defs/AchAccountTypeEnum" }, "tax_identifier": { "type": "string", "description": "Tax identifier is required if adding a billing info that is a consumer card in Brazil or in Argentina. This would be the customer's CPF/CNPJ (Brazil) and CUIT (Argentina). CPF, CNPJ and CUIT are tax identifiers for all residents who pay taxes in Brazil and Argentina respectively." }, "tax_identifier_type": { "description": "This field and a value of `cpf`, `cnpj` or `cuit` are required if adding a billing info that is an elo or hipercard type in Brazil or in Argentina.", "$ref": "#/$defs/TaxIdentifierTypeEnum" }, "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. The first billing info created on an account will always become primary. Adding additional billing infos provides the flexibility to mark another billing info as primary, or adding additional non-primary billing infos. This can be accomplished by passing the `primary_payment_method` with a value of `true`. When adding billing infos via the billing_info and /accounts endpoints, this value is not permitted, and will return an error if provided." }, "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." }, "external_hpp_type": { "$ref": "#/$defs/ExternalHppTypeEnum" }, "online_banking_payment_type": { "$ref": "#/$defs/OnlineBankingPaymentTypeEnum", "deprecated": true }, "card_type": { "$ref": "#/$defs/CardTypeEnum" }, "card_network_preference": { "description": "Represents the card network preference associated with the billing info for dual badged cards. Must be a supported card network.", "$ref": "#/$defs/CardNetworkEnum" }, "return_url": { "type": "string", "title": "Return URL", "description": "Specifies a URL to which a consumer will be redirected upon completion of a redirect payment flow. Only redirect payment flows operating through Adyen Components will utilize this return URL." }, "authentication_method": { "$ref": "#/$defs/UpiAutopayAuthenticationMethodEnum" }, "store_billing_info": { "type": "boolean", "description": "Whether to store this billing info onto its associated account. Defaults to `true`." } } }, "CardNetworkEnum": { "type": "string", "enum": [ "Bancontact", "CartesBancaires", "Dankort", "MasterCard", "Visa" ] }, "CardTypeEnum": { "type": "string", "enum": [ "American Express", "Dankort", "Diners Club", "Discover", "ELO", "Forbrugsforeningen", "Hipercard", "JCB", "Laser", "Maestro", "MasterCard", "Test Card", "Union Pay", "Unknown", "Visa", "Tarjeta Naranja" ] }, "ChannelEnum": { "type": "string", "enum": [ "advertising", "blog", "direct_traffic", "email", "events", "marketing_content", "organic_search", "other", "outbound_sales", "paid_search", "public_relations", "referral", "social_media" ] }, "CollectionMethodEnum": { "type": "string", "enum": [ "automatic", "manual" ] }, "CreditApplicationAllowedOriginTypeEnum": { "type": "string", "title": "Credit Application Allowed Origin Type", "description": "The origin type of a credit invoice that can be allowed in a credit application policy", "enum": [ "line_item_refund", "open_amount_refund", "immediate_change", "termination", "credit", "write_off", "refund", "external_refund", "carryforward_credit", "usage_correction", "prepayment", "gift_card", "carryforward_gift_credit" ] }, "CreditApplicationModeEnum": { "type": "string", "title": "Credit Application Mode", "description": "Determines which credit invoices are applied to invoices:\n- `all`: All available credit invoices are applied (default)\n- `none`: No credit invoices are applied automatically\n", "enum": [ "all", "none" ], "default": "all" }, "CreditApplicationPolicy": { "type": "object", "title": "Credit Application Policy", "description": "Controls whether credit invoices are automatically applied to new invoices.\nThe `mode` field determines the application behavior. When mode is `all`,\nthe optional `allowed_origins` array can restrict which credit invoice origins\nare applied.\n", "properties": { "mode": { "$ref": "#/$defs/CreditApplicationModeEnum" }, "allowed_origins": { "type": "array", "description": "Optional array of credit invoice origin types to allow when mode is `all`.\nIf not specified when mode is `all`, credits from all origins are applied.\nOnly valid when mode is `all`.\n", "items": { "$ref": "#/$defs/CreditApplicationAllowedOriginTypeEnum" } } }, "required": [ "mode" ] }, "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 this custom field was automatically copied from. Only present when the field was copied from another record.", "readOnly": true, "$ref": "#/$defs/SourceRecordTypeEnum" }, "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" } }, "DestinationTaxAddressSourceEnum": { "type": "string", "title": "Destination tax address source", "description": "The source of the address that will be used as the destinaion in determining taxes. Available only when the site is on an Elite plan. A value of \"destination\" refers to the \"Customer tax address\". A value of \"origin\" refers to the \"Business entity tax address\".", "default": "destination", "enum": [ "destination", "origin" ] }, "ExternalHppTypeEnum": { "type": "string", "description": "Use for Adyen HPP billing info. This should only be used as part of a pending purchase request, when the billing info is nested inside an account object.", "enum": [ "adyen" ] }, "GatewayTransactionTypeEnum": { "type": "string", "enum": [ "moto" ] }, "LineItemCreate": { "type": "object", "properties": { "currency": { "type": "string", "title": "Currency", "description": "3-letter ISO 4217 currency code. If `item_code`/`item_id` is part of the request then `currency` is optional, if the site has a single default currency. `currency` is required if `item_code`/`item_id` is present, and there are multiple currencies defined on the site. If `item_code`/`item_id` is not present `currency` is required.", "maxLength": 3 }, "unit_amount": { "type": "number", "format": "float", "title": "Unit amount", "description": "A positive or negative amount with `type=charge` will result in a positive `unit_amount`.\nA positive or negative amount with `type=credit` will result in a negative `unit_amount`.\nIf `item_code`/`item_id` is present, `unit_amount` can be passed in, to override the\n`Item`'s `unit_amount`. If `item_code`/`item_id` is not present then `unit_amount` is required.\n" }, "tax_inclusive": { "type": "boolean", "title": "Tax Inclusive?", "default": false, "description": "Determines whether or not tax is included in the unit amount. The Tax Inclusive Pricing feature (separate from the Mixed Tax Pricing feature) must be enabled to use this flag." }, "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. If `item_code`/`item_id` is part of the request then `description` must be absent.", "maxLength": 255 }, "item_code": { "type": "string", "title": "Item Code", "description": "Unique code to identify an item. Available when the Credit Invoices feature is enabled.", "pattern": "/^[a-z0-9_+-]+$/", "maxLength": 50 }, "item_id": { "type": "string", "title": "Item ID", "description": "System-generated unique identifier for an item. Available when the Credit Invoices feature is enabled.", "maxLength": 13 }, "revenue_schedule_type": { "title": "Revenue schedule type", "$ref": "#/$defs/LineItemRevenueScheduleTypeEnum" }, "type": { "title": "Type", "description": "Line item type. If `item_code`/`item_id` is present then `type` should not be present. If `item_code`/`item_id` is not present then `type` is required.", "$ref": "#/$defs/LineItemTypeEnum" }, "credit_reason_code": { "title": "Credit reason code", "description": "The reason the credit was given when line item is `type=credit`. When the Credit Invoices feature is enabled, the value can be set and will default to `general`. When the Credit Invoices feature is not enabled, the value will always be `null`.", "default": "general", "$ref": "#/$defs/PartialCreditReasonCodeEnum" }, "accounting_code": { "type": "string", "title": "Accounting Code", "description": "Accounting Code for the `LineItem`. If `item_code`/`item_id` is part of the request then `accounting_code` must be absent.", "pattern": "/^[a-z0-9_+-]+$/", "maxLength": 20 }, "liability_gl_account_id": { "type": "string", "title": "General Ledger Account ID", "description": "The ID of a general ledger account. General ledger accounts are\nonly accessible as a part of the Recurly RevRec Standard and\nRecurly RevRec Advanced features.\n", "maxLength": 13 }, "revenue_gl_account_id": { "type": "string", "title": "General Ledger Account ID", "description": "The ID of a general ledger account. General ledger accounts are\nonly accessible as a part of the Recurly RevRec Standard and\nRecurly RevRec Advanced features.\n", "maxLength": 13 }, "performance_obligation_id": { "type": "string", "title": "Performance Obligation ID", "description": "The ID of a performance obligation. Performance obligations are\nonly accessible as a part of the Recurly RevRec Standard and\nRecurly RevRec Advanced features.\n", "maxLength": 13 }, "tax_exempt": { "type": "boolean", "title": "Tax exempt?", "description": "`true` exempts tax on charges, `false` applies tax on charges. If not defined, then defaults to the Plan and Site settings. This attribute does not work for credits (negative line items). Credits are always applied post-tax. Pre-tax discounts should use the Coupons feature." }, "avalara_transaction_type": { "type": "integer", "title": "Avalara Transaction Type", "description": "Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the line item is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. If an `Item` is associated to the `LineItem`, then the `avalara_transaction_type` must be absent.", "minimum": 0 }, "avalara_service_type": { "type": "integer", "title": "Avalara Service Type", "description": "Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the line item is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. If an `Item` is associated to the `LineItem`, then the `avalara_service_type` must be absent.", "minimum": 0 }, "vertex_transaction_type": { "$ref": "#/$defs/VertexTransactionTypeEnum" }, "tax_code": { "type": "string", "maxLength": 50, "title": "Tax code", "description": "Optional field used by Avalara, Vertex, and Recurly's In-the-Box tax solution to determine taxation rules. You can pass in specific tax codes using any of these tax integrations. For Recurly's In-the-Box tax offering you can also choose to instead use simple values of `unknown`, `physical`, or `digital` tax codes." }, "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. If `item_code`/`item_id` is part of the request then `harmonized_system_code` must be absent.", "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. For Vertex tax calculations, this field will be used as the Vertex `product` field. If `item_code`/`item_id` is part of the request then `product_code` must be absent.", "maxLength": 50 }, "origin": { "title": "Origin", "description": "Origin `external_gift_card` is allowed if the Gift Cards feature is enabled on your site, `type` is `credit` and `tax_exempt` is `true` if you are using taxes. Set this value in order to track gift card credits from external gift cards (like InComm). It also skips billing information requirements. Origin `prepayment` is only allowed if `type` is `charge` and `tax_exempt` is left blank or set to true. This origin creates a charge and opposite credit on the account to be used for future invoices.", "$ref": "#/$defs/LineItemCreateOriginEnum" }, "custom_fields": { "$ref": "#/$defs/CustomFields" }, "start_date": { "type": "string", "format": "date-time", "title": "Start date", "description": "If an end date is present, this is value indicates the beginning of a billing time range. If no end date is present it indicates billing for a specific date. Defaults to the current date-time." }, "end_date": { "type": "string", "format": "date-time", "title": "End date", "description": "If this date is provided, it indicates the end of a time range." }, "origin_tax_address_source": { "$ref": "#/$defs/OriginTaxAddressSourceEnum" }, "destination_tax_address_source": { "$ref": "#/$defs/DestinationTaxAddressSourceEnum" } }, "required": [ "currency", "unit_amount", "type" ] }, "LineItemCreateOriginEnum": { "type": "string", "enum": [ "external_gift_card", "prepayment" ] }, "LineItemRevenueScheduleTypeEnum": { "type": "string", "enum": [ "at_invoice", "at_range_end", "at_range_start", "evenly", "never" ] }, "LineItemTypeEnum": { "type": "string", "enum": [ "charge", "credit" ] }, "NetTermsTypeEnum": { "type": "string", "title": "Net Terms Type", "description": "Optionally supplied string that may be either `net` or `eom` (end-of-month).\nWhen `net`, an invoice becomes past due the specified number of `Net Terms` days from the current date.\nWhen `eom` an invoice becomes past due the specified number of `Net Terms` days from the last day of the current month.\n", "enum": [ "net", "eom" ], "default": "net" }, "OnlineBankingPaymentTypeEnum": { "type": "string", "description": "Use for Online Banking billing info. This should only be used as part of a pending purchase request, when the billing info is nested inside an account object.", "enum": [ "ideal", "sofort" ] }, "OriginTaxAddressSourceEnum": { "type": "string", "title": "Origin tax address source", "description": "The source of the address that will be used as the origin in determining taxes. Available only when the site is on an Elite plan. A value of \"origin\" refers to the \"Business entity tax address\". A value of \"destination\" refers to the \"Customer tax address\".", "default": "origin", "enum": [ "origin", "destination" ] }, "PartialCreditReasonCodeEnum": { "type": "string", "enum": [ "general", "promotional", "service" ] }, "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", "$ref": "#/$defs/PaymentGatewayReferencesEnum" } } }, "PaymentGatewayReferencesEnum": { "type": "string", "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" ] }, "PreferredLocaleEnum": { "type": "string", "enum": [ "da-DK", "de-CH", "de-DE", "en-AU", "en-CA", "en-GB", "en-IE", "en-NZ", "en-US", "es-ES", "es-MX", "es-US", "fi-FI", "fr-BE", "fr-CA", "fr-CH", "fr-FR", "hi-IN", "it-IT", "ja-JP", "ko-KR", "nl-BE", "nl-NL", "pl-PL", "pt-BR", "pt-PT", "ro-RO", "ru-RU", "sk-SK", "sv-SE", "tr-TR", "zh-CN" ] }, "PriceSegmentIdOrCode": { "type": "string", "description": "The price segment ID or code. For ID no prefix is used e.g. `e28zov4fw0v2`. For requests, the code can also be used. Use prefix `code-`, e.g. `code-gold`.", "maxLength": 55, "pattern": "/^[a-z0-9_+-]+$/" }, "RevenueScheduleTypeEnum": { "type": "string", "enum": [ "at_range_end", "at_range_start", "evenly", "never" ] }, "ShippingAddressCreate": { "type": "object", "properties": { "nickname": { "type": "string", "maxLength": 255 }, "first_name": { "type": "string", "maxLength": 255 }, "last_name": { "type": "string", "maxLength": 255 }, "company": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "maxLength": 255 }, "vat_number": { "type": "string", "maxLength": 20 }, "phone": { "type": "string", "maxLength": 30 }, "street1": { "type": "string", "maxLength": 255 }, "street2": { "type": "string", "maxLength": 255 }, "city": { "type": "string", "maxLength": 255 }, "region": { "type": "string", "maxLength": 255, "description": "State or province." }, "postal_code": { "type": "string", "maxLength": 20, "description": "Zip or postal code." }, "geo_code": { "type": "string", "maxLength": 20, "description": "Code that represents a geographic entity (location or object). Only returned when Vertex or Avalara for Communications is enabled." }, "country": { "type": "string", "maxLength": 50, "description": "Country, 2-letter ISO 3166-1 alpha-2 code." } }, "required": [ "first_name", "last_name", "street1", "city", "postal_code", "country" ] }, "ShippingFeeCreate": { "type": "object", "properties": { "method_id": { "type": "string", "title": "Method ID", "description": "The id of the shipping method used to deliver the purchase. If `method_id` and `method_code` are both present, `method_id` will be used.", "maxLength": 13 }, "method_code": { "type": "string", "title": "Method Code", "description": "The code of the shipping method used to deliver the purchase. If `method_id` and `method_code` are both present, `method_id` will be used.", "maxLength": 50 }, "amount": { "type": "number", "format": "float", "title": "Amount", "description": "This is priced in the purchase's currency.", "minimum": 0 } } }, "SourceRecordTypeEnum": { "type": "string", "description": "The type of record a custom field was automatically copied from.", "enum": [ "account", "plan", "product", "subscription" ] }, "SubscriptionAddOnCreate": { "type": "object", "properties": { "code": { "type": "string", "title": "Add-on code", "maxLength": 50, "description": "If `add_on_source` is set to `plan_add_on` or left blank, then plan's add-on `code` should be used.\nIf `add_on_source` is set to `item`, then the `code` from the associated item should be used.\n" }, "add_on_source": { "$ref": "#/$defs/AddOnSourceEnum" }, "quantity": { "type": "integer", "title": "Quantity", "minimum": 0, "default": 1 }, "unit_amount": { "type": "number", "format": "float", "title": "Unit amount", "description": "Allows up to 2 decimal places. Optionally, override the add-on's default unit amount.\nIf the plan add-on's `tier_type` is `tiered`, `volume`, or `stairstep`, then `unit_amount` cannot be provided.\n", "minimum": 0, "maximum": 1000000 }, "unit_amount_decimal": { "type": "string", "format": "decimal", "title": "Unit Amount Decimal", "description": "Allows up to 9 decimal places. Optionally, override the add-on's default unit amount.\nIf the plan add-on's `tier_type` is `tiered`, `volume`, or `stairstep`, then `unit_amount_decimal` cannot be provided.\nIf `unit_amount_decimal` is provided, `unit_amount` cannot be provided.\n", "minimum": 0, "maximum": 1000000 }, "tiers": { "type": "array", "title": "Tiers", "items": { "$ref": "#/$defs/SubscriptionAddOnTier" }, "minItems": 1, "description": "If the plan add-on's `tier_type` is `flat`, then `tiers` must be absent. The `tiers` object\nmust include one to many tiers with `ending_quantity` and `unit_amount`.\nThere must be one tier without an `ending_quantity` value which represents the final tier.\nSee our [Guide](https://recurly.com/developers/guides/item-addon-guide.html)\nfor an overview of how to configure quantity-based pricing models.\n" }, "percentage_tiers": { "type": "array", "title": "Percentage Tiers", "items": { "$ref": "#/$defs/SubscriptionAddOnPercentageTier" }, "minItems": 1, "description": "If percentage tiers are provided in the request, all existing percentage tiers on the Subscription Add-on will be\nremoved and replaced by the percentage tiers in the request. There must be one tier without ending_amount value\nwhich represents the final tier. Use only if add_on.tier_type is tiered or volume and add_on.usage_type is\npercentage. This feature is currently in development and requires approval and enablement, please contact support.\n" }, "usage_percentage": { "type": "number", "format": "float", "title": "Usage Percentage", "minimum": 0, "maximum": 100, "description": "The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0. Required if `add_on_type` is usage and `usage_type` is percentage. Must be omitted otherwise. `usage_percentage` does not support tiers. See our [Guide](https://recurly.com/developers/guides/usage-based-billing-guide.html) for an overview of how to configure usage add-ons." }, "revenue_schedule_type": { "title": "Revenue schedule type", "$ref": "#/$defs/RevenueScheduleTypeEnum" } }, "required": [ "code" ] }, "SubscriptionAddOnPercentageTier": { "type": "object", "properties": { "ending_amount": { "type": "number", "format": "float", "title": "Ending amount", "minimum": 1, "maximum": 9999999999999.99, "description": "Ending amount for the tier. Allows up to 2 decimal places. Must be left empty if it is the final tier." }, "usage_percentage": { "type": "string", "title": "Usage Percentage", "minimum": 0, "maximum": 100, "description": "The percentage taken of the monetary amount of usage tracked.\nThis can be up to 4 decimal places represented as a string.\n" } } }, "SubscriptionAddOnTier": { "type": "object", "properties": { "ending_quantity": { "type": "integer", "title": "Ending quantity", "minimum": 1, "maximum": 999999999, "description": "Ending quantity for the tier. This represents a unit amount for unit-priced add ons. Must be left empty if it is the final tier." }, "unit_amount": { "type": "number", "format": "float", "title": "Unit amount", "minimum": 0, "maximum": 1000000, "description": "Allows up to 2 decimal places. Optionally, override the tiers' default unit amount. If add-on's `add_on_type` is `usage` and `usage_type` is `percentage`, cannot be provided." }, "unit_amount_decimal": { "type": "string", "title": "Unit amount decimal", "description": "Allows up to 9 decimal places. Optionally, override tiers' default unit amount.\nIf `unit_amount_decimal` is provided, `unit_amount` cannot be provided.\nIf add-on's `add_on_type` is `usage` and `usage_type` is `percentage`, cannot be provided.\n" }, "usage_percentage": { "type": "string", "title": "Usage Percentage", "description": "(deprecated) -- Use the percentage_tiers object instead.", "deprecated": true } } }, "SubscriptionCreateProrationSettings": { "type": "object", "title": "Proration Settings", "description": "Allows you to control how any resulting charges will be calculated and prorated.", "properties": { "charge": { "$ref": "#/$defs/SubscriptionCreateProrationSettingsChargeEnum" } } }, "SubscriptionCreateProrationSettingsChargeEnum": { "type": "string", "title": "Charge", "description": "Determines how the amount charged is determined for this change", "default": "prorated_amount", "enum": [ "full_amount", "prorated_amount" ] }, "SubscriptionPurchase": { "type": "object", "properties": { "plan_code": { "type": "string", "title": "Plan code" }, "plan_id": { "type": "string", "title": "Plan ID", "maxLength": 13 }, "unit_amount": { "type": "number", "format": "float", "title": "Custom subscription pricing", "description": "Override the unit amount of the subscription plan by setting this value. If not provided, the subscription will inherit the price from the subscription plan for the provided currency.", "minimum": 0, "maximum": 1000000 }, "price_segment_id": { "$ref": "#/$defs/PriceSegmentIdOrCode" }, "tax_inclusive": { "type": "boolean", "title": "Tax Inclusive?", "default": false, "description": "Determines whether or not tax is included in the unit amount. The Tax Inclusive Pricing feature (separate from the Mixed Tax Pricing feature) must be enabled to use this flag." }, "quantity": { "type": "integer", "title": "Quantity", "description": "Optionally override the default quantity of 1.", "default": 1, "minimum": 0 }, "add_ons": { "type": "array", "title": "Add-ons", "items": { "$ref": "#/$defs/SubscriptionAddOnCreate" } }, "custom_fields": { "$ref": "#/$defs/CustomFields" }, "shipping": { "title": "Shipping address", "description": "Create a shipping address on the account and assign it to the subscription.", "$ref": "#/$defs/SubscriptionShippingPurchase" }, "trial_ends_at": { "type": "string", "format": "date-time", "title": "Trial ends at", "description": "If set, overrides the default trial behavior for the subscription. When the current date time or a past date time is provided the subscription will begin with no trial phase (overriding any plan default trial). When a future date time is provided the subscription will begin with a trial phase ending at the specified date time." }, "starts_at": { "type": "string", "format": "date-time", "title": "Start date", "description": "If set, the subscription will begin on this specified date. The subscription will apply the setup fee and trial period, unless the plan has no trial. Omit this field if the subscription should be started immediately." }, "next_bill_date": { "type": "string", "format": "date-time", "title": "Next bill date", "description": "If present, this sets the date the subscription's next billing period will start (`current_period_ends_at`). This can be used to align the subscription’s billing to a specific day of the month. The initial invoice will be prorated for the period between the subscription's activation date and the billing period end date. Subsequent periods will be based off the plan interval. For a subscription with a trial period, this will change when the trial expires." }, "total_billing_cycles": { "type": "integer", "title": "Total billing cycles", "description": "The number of cycles/billing periods in a term. When `remaining_billing_cycles=0`, if `auto_renew=true` the subscription will renew and a new term will begin, otherwise the subscription will expire.", "minimum": 1 }, "renewal_billing_cycles": { "type": "integer", "title": "Renewal billing cycles", "description": "If `auto_renew=true`, when a term completes, `total_billing_cycles` takes this value as the length of subsequent terms. Defaults to the plan's `total_billing_cycles`." }, "auto_renew": { "type": "boolean", "default": true, "title": "Auto renew", "description": "Whether the subscription renews at the end of its term." }, "revenue_schedule_type": { "title": "Revenue schedule type", "$ref": "#/$defs/RevenueScheduleTypeEnum" }, "ramp_intervals": { "type": "array", "title": "Ramp Intervals", "description": "The new set of ramp intervals for the subscription.", "items": { "$ref": "#/$defs/SubscriptionRampInterval" } }, "credit_application_policy": { "$ref": "#/$defs/CreditApplicationPolicy" }, "terms_and_conditions": { "type": "string", "title": "Terms and conditions", "description": "Specify custom notes to add or override Terms and Conditions. Custom notes will stay with a subscription on all renewals." }, "customer_notes": { "type": "string", "title": "Customer notes", "description": "Specify custom notes to add or override Customer Notes. Custom notes will stay with a subscription on all renewals." }, "vat_reverse_charge_notes": { "type": "string", "title": "VAT reverse charge notes", "description": "Specify custom notes to add or override VAT reverse charge notes. Custom notes will stay with a subscription on all renewals." }, "bulk": { "type": "boolean", "description": "Optional field to be used only when needing to bypass the 60 second limit on creating subscriptions. Should only be used when creating subscriptions in bulk from the API.", "default": false }, "proration_settings": { "$ref": "#/$defs/SubscriptionCreateProrationSettings" } }, "required": [ "plan_code" ] }, "SubscriptionRampInterval": { "type": "object", "title": "Subscription Ramp Interval", "properties": { "starting_billing_cycle": { "type": "integer", "description": "Represents the billing cycle where a ramp interval starts.", "default": 1 }, "unit_amount": { "type": "number", "format": "float", "description": "Represents the price for the ramp interval." } } }, "SubscriptionShippingPurchase": { "type": "object", "title": "Subscription shipping details", "properties": { "method_id": { "type": "string", "title": "Service ID", "description": "The id of the shipping method used to deliver the subscription. If `method_id` and `method_code` are both present, `method_id` will be used.", "maxLength": 13 }, "method_code": { "type": "string", "title": "Service Code", "description": "The code of the shipping method used to deliver the subscription. If `method_id` and `method_code` are both present, `method_id` will be used.", "maxLength": 50 }, "amount": { "type": "number", "format": "float", "title": "Assigns the subscription's shipping cost. If this is greater than zero then a `method_id` or `method_code` is required." }, "expected_first_delivery_at": { "type": "string", "format": "date-time", "title": "Expected first delivery date", "description": "The expected date of the first delivery for the subscription." } } }, "TaxIdentifierTypeEnum": { "type": "string", "enum": [ "cpf", "cnpj", "cuit" ] }, "UpiAutopayAuthenticationMethodEnum": { "type": "string", "title": "Authentication Method", "description": "UPI Autopay authentication method. Specifies how the customer authorizes the enrollment mandate. Defaults to 'vpa' if omitted.", "enum": [ "vpa", "qr-code", "app-deep-links" ] }, "VertexTransactionTypeEnum": { "type": "string", "title": "Vertex Transaction Type", "description": "Used by Vertex for tax calculations. Possible values are sale, rental, lease.", "enum": [ "sale", "rental", "lease" ] } } }