{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://artifacts.apis.io/two/json-schema/two-create-order-request-schema-schema.json", "title": "CreateOrderRequestSchema", "x-generated": "2026-10-29", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/two-openapi.yaml#/components/schemas/CreateOrderRequestSchema", "properties": { "gross_amount": { "anyOf": [ { "format": "decimal", "pattern": "^-?[0-9]+(\\.[0-9]{0,2})?", "type": "string" }, { "type": "null" } ], "default": null, "description": "net_amount + tax_amount", "title": "Gross Amount" }, "net_amount": { "description": "Total before tax — sum of all line items excluding tax.", "format": "decimal", "pattern": "^-?[0-9]+(\\.[0-9]{0,2})?", "title": "Net Amount", "type": "string" }, "currency": { "$ref": "#/$defs/CurrencyEnum", "description": "Currency code in ISO 4217 format. E.g. 'NOK'" }, "discount_amount": { "default": "0.00", "deprecated": true, "description": "Deprecated, discount amount is only applicable at line item level", "format": "decimal", "pattern": "^-?[0-9]+(\\.[0-9]{0,2})?", "title": "Discount Amount", "type": "string" }, "discount_rate": { "default": "0.000000", "deprecated": true, "description": "Deprecated, discount rate is only applicable at line item level", "format": "decimal", "pattern": "^-?[0-9]+(\\.[0-9]{0,6})?", "title": "Discount Rate", "type": "string" }, "tax_amount": { "description": "Total tax (e.g. VAT) applied to the order.", "format": "decimal", "pattern": "^-?[0-9]+(\\.[0-9]{0,2})?", "title": "Tax Amount", "type": "string" }, "buyer_department": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Department the purchase is to be registered on", "title": "Buyer Department" }, "buyer_project": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Project the purchase is to be registered on", "title": "Buyer Project" }, "buyer_purchase_order_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Purchase order number to attribute to the order", "title": "Buyer Purchase Order Number" }, "buyer_reference": { "anyOf": [ { "maxLength": 140, "type": "string" }, { "type": "null" } ], "default": null, "description": "General buyer reference field for information that is not covered by the specific reference fields, e.g. PO-number. Note: Maximum 140 characters", "title": "Buyer Reference" }, "buyer_vat_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Vat number associated with the buyer company", "title": "Buyer Vat Number" }, "line_items": { "description": "List of the line items that constitute the order", "items": { "$ref": "#/$defs/LineItemRequestSchema" }, "title": "Line Items", "type": "array" }, "merchant_order_id": { "description": "Your order ID to register against the order", "title": "Merchant Order Id", "type": "string" }, "merchant_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Field set by merchant for adding a reference to be used internally by the merchant. Does not appear on invoice.", "title": "Merchant Reference" }, "merchant_additional_info": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Additional info the merchant can connect to the order", "title": "Merchant Additional Info" }, "invoice_details": { "anyOf": [ { "$ref": "#/$defs/InvoiceDetailsRequestSchema" }, { "type": "null" } ], "default": null, "description": "Invoice details are provided by the merchant via Merchant Portal when invoice_type is DIRECT_INVOICE, Two Bank or a 3rd-party bank when invoice_type is FUNDED_INVOICE and empty when invoice_type is CARD." }, "merchant_short_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "deprecated": true, "description": "Deprecated. Use merchant_id where possible.", "title": "Merchant Short Name" }, "shipping_details": { "anyOf": [ { "$ref": "#/$defs/ShippingDetailsSchema" }, { "type": "null" } ], "default": null, "description": "Shipping details including carrier information and delivery method. For merchants offering multiple fulfillment options, the `delivery_method` field is needed for order validation and processing workflow purposes." }, "order_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "General note/message from the buyer to the merchant", "title": "Order Note" }, "billing_address": { "anyOf": [ { "$ref": "#/$defs/CreateAddressRequestSchema" }, { "type": "null" } ], "default": null, "description": "Order billing address" }, "shipping_address": { "anyOf": [ { "$ref": "#/$defs/CreateAddressRequestSchema" }, { "type": "null" } ], "default": null, "description": "Order shipping address" }, "tax_subtotals": { "anyOf": [ { "items": { "$ref": "#/$defs/TaxSubtotalSchema" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "List of tax subtotals for unique tax brackets", "title": "Tax Subtotals" }, "terms": { "anyOf": [ { "description": "For backwards compatibility, `type` can be omitted for instalment terms, if the fields period and number_of_instalments are populated. It is recommended that that clients always provide a type value.", "oneOf": [ { "$ref": "#/$defs/OrderInstalmentTerms" }, { "$ref": "#/$defs/OrderNetTerms" } ] }, { "type": "null" } ], "default": null, "description": "If set, the order will be placed with the specified terms. This is in beta and only open for limited users. Please contact us if you would like to integrate with this feature. It cannot be used with invoice_details.due_date, invoice_details.due_in_days and invoice_details.invoice_issue_date.", "title": "Terms" }, "merchant_invoice_branding_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ID of the merchant's invoice branding configuration", "title": "Merchant Invoice Branding Id" }, "merchant_invoice_store_branding_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ID of the merchant's store-specific invoice branding configuration", "title": "Merchant Invoice Store Branding Id" }, "order_placed_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "Date order was placed (UTC). If not specified, defaults to current timestamp.", "title": "Order Placed Date" }, "order_type": { "anyOf": [ { "$ref": "#/$defs/OrderTypeEnum" }, { "type": "null" } ], "default": null, "description": "Type of order (Buyer or Merchant initiated)" }, "sale_country_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional sale country code (ISO 3166 Alpha-2) to use for this order, if null defaults to buyer country code.", "title": "Sale Country Code" }, "merchant_payout_account_alias": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional payee account alias account identifier for multiple accounts setup.", "title": "Merchant Payout Account Alias" }, "recurring": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "If set to true, an invoice will be generated periodically according to the specification provided in recurring_details", "title": "Recurring" }, "merchant_invoice_branding_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Reference to merchant's invoice branding configuration", "title": "Merchant Invoice Branding Reference" }, "merchant_invoice_store_branding_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Reference to merchant's store-specific invoice branding configuration", "title": "Merchant Invoice Store Branding Reference" }, "buyer": { "anyOf": [ { "$ref": "#/$defs/NonStrictBuyerSchema" }, { "type": "null" } ], "default": null, "description": "Fields representing the buyer" }, "electronic_invoice_recipient": { "anyOf": [ { "$ref": "#/$defs/ElectronicInvoiceRecipient" }, { "type": "null" } ], "default": null, "description": "electronic_invoice_recipient" }, "preferred_distribution_method": { "anyOf": [ { "$ref": "#/$defs/DistributionMethodEnum" }, { "type": "null" } ], "default": null, "description": "Allows merchant to set the method of distribution for the invoice and credit notes of the order, if not set will default to all methods" }, "recurring_details": { "anyOf": [ { "$ref": "#/$defs/RecurringDetailsSchema" }, { "type": "null" } ], "default": null, "description": "Currently not available" }, "merchant_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "A globally unique merchant ID set by Two.", "title": "Merchant Id" }, "merchant_urls": { "anyOf": [ { "$ref": "#/$defs/CreateOrderMerchantUrlsSchema" }, { "type": "null" } ], "default": null, "description": "List of urls hosted by the merchant." }, "order_origination": { "anyOf": [ { "$ref": "#/$defs/OrderOriginationEnum" }, { "type": "null" } ], "default": null, "description": "IN_STORE orders are not enabled by default. Please reach out to us if you would like to discuss IN_STORE orders." }, "tracking_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Tracking ID from `POST /order_intent`", "title": "Tracking Id" }, "vendor_name": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "This is an optional vendor name that is used to refer to the seller in a marketplace setup.", "title": "Vendor Name" }, "vendor_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional vendor ID for your reference", "title": "Vendor Id" }, "merchant_user_id": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Your internal ID of the user (the employee of your business customer) registered for one-click purchase through the Two Trade Account Onboarding API.", "title": "Merchant User Id" }, "billing_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "ID for the billing account linked to this order. Do not pass terms when setting billing_account_id; billing account payment terms take precedence. The billing account buyer company must match the order buyer company. The billing account must belong to the same merchant as the order. Cannot be combined with INSTALMENTS terms or terms.duration_days_calculated_from.", "title": "Billing Account Id" }, "disallow_portal_mutation": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "If set to true, state-mutating actions (fulfill, cancel, refund) cannot be performed on this order through the merchant portal. Use this for orders managed by external systems (ERPs, PSPs) that track order state via the API, to prevent desynchronization.", "title": "Disallow Portal Mutation" }, "credit_line_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "ID of the credit line used to fund the order, created through the Two Credit Line API.", "title": "Credit Line Id" } }, "required": [ "billing_address", "buyer", "currency", "gross_amount", "line_items", "merchant_order_id", "net_amount", "tax_amount", "tax_subtotals" ], "type": "object", "$defs": { "BankAccountSchema": { "properties": { "id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "bban": { "anyOf": [ { "maxLength": 30, "minLength": 7, "pattern": "^[0-9A-Za-z]*$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Bban" }, "iban": { "anyOf": [ { "maxLength": 34, "minLength": 15, "pattern": "^[0-9A-Za-z]*$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Iban" }, "bic": { "anyOf": [ { "maxLength": 12, "minLength": 8, "pattern": "^[0-9A-Za-z]*$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Bic" }, "country_code": { "anyOf": [ { "$ref": "#/$defs/CountryCodeEnum" }, { "type": "null" } ], "default": null }, "branch_sort_code": { "anyOf": [ { "maxLength": 9, "pattern": "^[0-9]*$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Branch Sort Code" }, "local_account_number": { "anyOf": [ { "maxLength": 12, "minLength": 8, "pattern": "^[0-9]*$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Local Account Number" }, "organization_name": { "anyOf": [ { "maxLength": 140, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "title": "Organization Name" }, "organization_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Organization Number" }, "description": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "kid_type": { "anyOf": [ { "$ref": "#/$defs/KidTypeEnum" }, { "type": "null" } ], "default": null } }, "title": "BankAccountSchema", "type": "object" }, "BarCodeSchema": { "properties": { "value": { "description": "The identifier as a string", "title": "Value", "type": "string" }, "type": { "description": "Type of the identifier. Can be either \"SKU\" or a Global Trade Item Number (GTIN) type like \"UPC\", \"EAN\", \"GS1\".", "title": "Type", "type": "string" } }, "required": [ "value", "type" ], "title": "BarCodeSchema", "type": "object" }, "CallbackAuthTypeEnum": { "enum": [ "BEARER" ], "title": "CallbackAuthTypeEnum", "type": "string" }, "CompanyCanonicalIdSchema": { "additionalProperties": false, "description": "A schema that represents a company only by its canonical ID.\nIntended for use in requests to our API to create order intents and orders.\nUse the Two Company Search API to retrieve the canonical_id for a company.\n\nIMPORTANT: This schema forbids extra fields to prevent silent data loss.\nIf additional company fields are provided, use CompanySchema instead.", "properties": { "company_canonical_id": { "description": "Unique canonical ID representing this company. Retrieve this from the Two Company Search API.", "pattern": "^[a-zA-Z0-9]+$", "title": "Company Canonical Id", "type": "string" } }, "required": [ "company_canonical_id" ], "title": "CompanyCanonicalIdSchema", "type": "object" }, "CompanySchema": { "description": "Standard company schema with required fields for full company identification.\nExtends NonStrictCompanySchema and makes key fields required.", "properties": { "id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Internal company Id", "title": "Id" }, "country_prefix": { "$ref": "#/$defs/CountryCodeEnum", "description": "Country code in ISO 3166-1 alpha-2 format" }, "organization_number": { "description": "National id of the buyer company", "title": "Organization Number", "type": "string" }, "company_name": { "default": null, "description": "Legal name of the buyer company", "maxLength": 255, "minLength": 1, "title": "Company Name", "type": "string" }, "company_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Type of company placing the order", "title": "Company Type" }, "company_canonical_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Unique canonical ID representing this company", "title": "Company Canonical Id" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Company's website", "title": "Website" } }, "required": [ "country_prefix", "organization_number" ], "title": "CompanySchema", "type": "object" }, "CountryCodeEnum": { "enum": [ "AD", "AE", "AL", "AM", "AO", "AR", "AT", "AU", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BN", "BO", "BR", "BS", "BW", "CA", "CG", "CH", "CL", "CM", "CO", "CR", "CY", "CZ", "DE", "DJ", "DK", "DO", "DZ", "EC", "EE", "EG", "ES", "ET", "FI", "FJ", "FR", "GA", "GB", "GE", "GH", "GN", "GQ", "GR", "GT", "GY", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IN", "IQ", "IS", "IT", "JM", "JO", "JP", "KE", "KG", "KH", "KR", "KW", "KZ", "LA", "LB", "LI", "LK", "LT", "LU", "LV", "LR", "MA", "MC", "MD", "ME", "MG", "MK", "MN", "MR", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NE", "NG", "NL", "NO", "NP", "NZ", "OM", "PA", "PE", "PG", "PH", "PK", "PL", "PT", "PY", "QA", "RO", "RS", "RW", "SA", "SE", "SG", "SI", "SK", "SL", "SN", "SR", "SV", "SZ", "TD", "TG", "TH", "TJ", "TM", "TN", "TR", "TT", "TZ", "UA", "UG", "US", "UY", "UZ", "VN", "ZA", "ZM" ], "title": "CountryCodeEnum", "type": "string" }, "CreateAddressRequestSchema": { "properties": { "organization_name": { "title": "Organization Name", "type": "string" }, "street_address": { "maxLength": 255, "title": "Street Address", "type": "string" }, "country": { "$ref": "#/$defs/CountryCodeEnum" }, "postal_code": { "title": "Postal Code", "type": "string" }, "city": { "title": "City", "type": "string" }, "region": { "default": "", "title": "Region", "type": "string" } }, "required": [ "organization_name", "street_address", "country", "postal_code", "city" ], "title": "CreateAddressRequestSchema", "type": "object" }, "CreateOrderMerchantUrlsSchema": { "description": "Request-side merchant URLs: enforces an http(s) scheme on inbound URLs.\n\nThe scheme validators live here rather than on OrderMerchantUrlsSchema so\nthey only run when parsing a request body. Response schemas\n(OrderResponseSchema, VerifyUserResponseSchema) embed the plain\nOrderMerchantUrlsSchema and must never re-validate stored URLs on read - a\nlegacy or schemeless value persisted before this rule existed would\notherwise break order reads (ISEC-87).", "properties": { "merchant_confirmation_url": { "description": "URL to which you want to redirect your users upon successful order verification.", "title": "Merchant Confirmation Url", "type": "string" }, "merchant_cancel_order_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to which you want to redirect your users when they cancel an order.", "title": "Merchant Cancel Order Url" }, "merchant_edit_order_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Merchant Edit Order Url" }, "merchant_order_verification_pending_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Merchant Order Verification Pending Url" }, "merchant_order_verification_failed_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Merchant Order Verification Failed Url" }, "merchant_invoice_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Merchant Invoice Url" }, "merchant_shipping_document_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Merchant Shipping Document Url" }, "merchant_document_urls": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Merchant Document Urls" }, "merchant_order_verified_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Merchant Order Verified Url" }, "merchant_order_callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Merchant Order Callback Url" }, "merchant_order_callback_auth": { "anyOf": [ { "$ref": "#/$defs/OrderMerchantCallbackAuthSchema" }, { "type": "null" } ], "default": null } }, "required": [ "merchant_confirmation_url" ], "title": "CreateOrderMerchantUrlsSchema", "type": "object" }, "CurrencyEnum": { "enum": [ "CHF", "CZK", "DKK", "EUR", "GBP", "INR", "MXN", "NOK", "PLN", "RON", "SEK", "USD" ], "title": "CurrencyEnum", "type": "string" }, "DeliveryMethodEnum": { "description": "Enum for types of shipping methods", "enum": [ "PICKUP_STORE", "PICKUP_POINT", "DELIVERED_TO_SHIPPING_ADDRESS", "DELIVERED_DIGITALLY", "EXPRESS_PICKUP_POINT", "EXPRESS_SHIPPING_ADDRESS", "OTHER" ], "title": "DeliveryMethodEnum", "type": "string" }, "DistributionMethodEnum": { "enum": [ "EMAIL", "ELECTRONIC_INVOICE" ], "title": "DistributionMethodEnum", "type": "string" }, "DueDateCalculationScheme": { "description": "Scheme for calculating invoice due dates for orders.\nWhen set, modifies the due_in_days calculation based on the scheme type.", "enum": [ "END_OF_MONTH", "END_OF_WEEK" ], "title": "DueDateCalculationScheme", "type": "string" }, "ElectronicInvoiceRecipient": { "properties": { "id": { "title": "Id", "type": "string" }, "type": { "$ref": "#/$defs/ElectronicInvoiceRecipientTypeEnum" }, "operator_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Operator Id" } }, "required": [ "id", "type" ], "title": "ElectronicInvoiceRecipient", "type": "object" }, "ElectronicInvoiceRecipientTypeEnum": { "enum": [ "NO_ORGNUMBER", "SE_ORGNUMBER", "GLN", "DK_ORGNUMBER", "FI_ORGNUMBER", "FINVOICE" ], "title": "ElectronicInvoiceRecipientTypeEnum", "type": "string" }, "InvoiceDetailsRequestSchema": { "properties": { "payee": { "anyOf": [ { "$ref": "#/$defs/BankAccountSchema" }, { "type": "null" } ], "default": null }, "payment_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Payment Reference" }, "payment_reference_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Payment Reference Type" }, "payment_reference_message": { "default": "", "description": "Text that will be attached to the payment in order for the merchant to reconcile the payment.", "title": "Payment Reference Message", "type": "string" }, "payment_reference_ocr": { "default": "", "description": "A string of numbers that will be attached to the payment in order for the merchant to reconcile the payment. E.g. \"KID-nummer\" in Norway.", "title": "Payment Reference Ocr", "type": "string" }, "payment_status": { "anyOf": [ { "$ref": "#/$defs/PaymentStatusEnum" }, { "type": "null" } ], "default": null }, "due_in_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "deprecated": true, "description": "Please add terms to order instead, with type NET_TERMS and duration_days", "title": "Due In Days" }, "invoice_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Invoice Number" }, "invoice_issue_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "title": "Invoice Issue Date" }, "due_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "title": "Due Date" }, "invoice_emails": { "anyOf": [ { "items": { "format": "email", "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "We will send invoices to all of the email addresses.", "title": "Invoice Emails" } }, "title": "InvoiceDetailsRequestSchema", "type": "object" }, "KidTypeEnum": { "enum": [ "MOD_10", "MOD_11", "NONE" ], "title": "KidTypeEnum", "type": "string" }, "LineItemRequestSchema": { "properties": { "name": { "description": "Short name of the product", "title": "Name", "type": "string" }, "description": { "description": "Longer product description", "title": "Description", "type": "string" }, "line_item_reference": { "anyOf": [ { "minLength": 1, "pattern": "^[0-9A-Za-z_-]*$", "type": "string" }, { "type": "null" } ], "default": null, "description": "Your line item reference", "title": "Line Item Reference" }, "discount_amount": { "default": "0.00", "description": "Discount applied to line item (defaults to 0.0), excluded tax", "format": "decimal", "pattern": "^-?[0-9]+(\\.[0-9]{0,2})?", "title": "Discount Amount", "type": "string" }, "gross_amount": { "description": "net_amount + tax_amount", "format": "decimal", "pattern": "^-?[0-9]+(\\.[0-9]{0,2})?", "title": "Gross Amount", "type": "string" }, "net_amount": { "description": "(quantity * unit_price) - discount_amount", "format": "decimal", "pattern": "^-?[0-9]+(\\.[0-9]{0,2})?", "title": "Net Amount", "type": "string" }, "quantity": { "description": "Number of units for the specific line item (up to 8 decimal places)", "format": "decimal", "pattern": "^-?[0-9]+(\\.[0-9]{0,8})?", "title": "Quantity", "type": "string" }, "unit_price": { "description": "The price of one unit excluding tax and discount (up to 6 decimal places)", "format": "decimal", "pattern": "^-?[0-9]+(\\.[0-9]{0,6})?", "title": "Unit Price", "type": "string" }, "tax_amount": { "description": "net_amount * tax_rate", "format": "decimal", "pattern": "^-?[0-9]+(\\.[0-9]{0,2})?", "title": "Tax Amount", "type": "string" }, "tax_rate": { "description": "Tax rate on the line item level", "format": "decimal", "pattern": "^-?[0-9]+(\\.[0-9]{0,6})?", "title": "Tax Rate", "type": "string" }, "tax_class_name": { "description": "A description of the tax class (e.g. 'VAT 20%')", "title": "Tax Class Name", "type": "string" }, "tax_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Tax code from the tax registry (e.g. 'ES_IVA_STANDARD'). When provided, it must exist in the registry and populates tax metadata for e-invoicing. The full tax rules are applied when an order is created or changed, not on an order intent. Optional: if omitted, backward-compatible defaults are used.", "title": "Tax Code" }, "tax_exemption_reason_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "EN 16931 / PEPPOL BT-121 exemption reason code (e.g. 'VATEX-EU-132'). Required when the tax_code's registry entry has requires_exemption_reason=True and no default exemption_reason_code is defined. When supplied, overrides the registry default.", "title": "Tax Exemption Reason Code" }, "quantity_unit": { "description": "Unit like kg, l, pcs, etc.", "title": "Quantity Unit", "type": "string" }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Link to the image of the product.", "title": "Image Url" }, "product_page_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Link to the store product page.", "title": "Product Page Url" }, "type": { "$ref": "#/$defs/LineItemTypeEnum", "description": "Product type." }, "details": { "anyOf": [ { "$ref": "#/$defs/ProductDetailsSchema" }, { "type": "null" } ], "default": null, "description": "Meta-information and identifiers for the line item." }, "prototype_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Prototype id", "title": "Prototype Id" }, "vendor_name": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Vendor for line item", "title": "Vendor Name" }, "merchant_child_order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "In the case that the order created with Two is used to cover multiple orders on the merchant's side, this field could be referencing the merchant order that each line item originates from. This is analogous to how the merchant_order_id on the order itself can be used to map a Two order one-to-one with a merchant order. Depending on your configuration with Two, line items may be grouped by this value in the resulting invoice and the value may be rendered as a reference for each group of line items. In marketplace situations (multiple sub-vendors), this is typically combined with the vendor_name field on the line item, to indicate a vendor per child order.", "title": "Merchant Child Order Id" } }, "required": [ "name", "description", "gross_amount", "net_amount", "quantity", "unit_price", "tax_amount", "tax_rate", "tax_class_name", "quantity_unit", "type" ], "title": "LineItemRequestSchema", "type": "object" }, "LineItemTypeEnum": { "enum": [ "DIGITAL", "PHYSICAL", "SHIPPING_FEE", "GIFTCARD", "SERVICE", "BUYER_FEE", "OTHER" ], "title": "LineItemTypeEnum", "type": "string" }, "MerchantCustomerIdSchema": { "description": "A buyer company referenced by your own ID for the customer (trade account). Two takes the\ncompany and the invoicing details from that customer record.\n\nIMPORTANT: Reference the customer or give full company details, never both. Mixing\nmerchant_customer_id with inline company fields is rejected; fields we do not recognise are\nignored, so dropping a field from the API later cannot start rejecting callers who still\nsend it.", "properties": { "merchant_customer_id": { "description": "Your ID for the customer (trade account) this order is for.", "minLength": 1, "title": "Merchant Customer Id", "type": "string" } }, "required": [ "merchant_customer_id" ], "title": "MerchantCustomerIdSchema", "type": "object" }, "MerchantUserIdSchema": { "description": "A buyer representative referenced by your own ID for the user. Two takes the person's\ndetails from that user record.\n\nIMPORTANT: Reference the user or give full representative details, never both. Mixing\nmerchant_user_id with inline representative fields is rejected; fields we do not recognise\nare ignored, so dropping a field from the API later cannot start rejecting callers who\nstill send it.", "properties": { "merchant_user_id": { "description": "Your ID for the user placing this order.", "minLength": 1, "title": "Merchant User Id", "type": "string" } }, "required": [ "merchant_user_id" ], "title": "MerchantUserIdSchema", "type": "object" }, "NonStrictBuyerSchema": { "description": "# The name is kept as NonStrictBuyerSchema for backward compatibility.\nUsed only for the CreateOrderRequestSchema where validation rules might differ,\nfor example when a `billing_account_id` or `merchant_customer_id` is passed.\nIt allows the company to be identified by full details, canonical ID, or be omitted.", "properties": { "representative": { "description": "Who the order is for. Reference one of your users with merchant_user_id, or give full representative details.", "oneOf": [ { "$ref": "#/$defs/MerchantUserIdSchema" }, { "$ref": "#/$defs/StrictRepresentativeSchema" } ], "title": "Representative" }, "company": { "default": null, "description": "Fields to capture the details of the company for which the order is intended. Reference one of your customers (trade accounts) with merchant_customer_id, or assign a CompanyFromCanonicalIdRequestSchema instance to this field using a canonical id retrieved from our company search API, or give full company details. This structure may be omitted entirely when creating an order, if a billing account or trade account are referenced in the order itself.", "oneOf": [ { "$ref": "#/$defs/MerchantCustomerIdSchema" }, { "$ref": "#/$defs/CompanyCanonicalIdSchema" }, { "$ref": "#/$defs/CompanySchema" }, { "type": "null" } ], "title": "Company" } }, "required": [ "representative", "company" ], "title": "NonStrictBuyerSchema", "type": "object" }, "OrderInstalmentTerms": { "description": "By setting these fields, a merchant can create an instalment order with the specified terms.", "properties": { "type": { "const": "INSTALMENTS", "default": "INSTALMENTS", "title": "Type", "type": "string" }, "period": { "$ref": "#/$defs/TermsPeriod", "description": "The time between two instalments. QUARTERLY must be enabled for the merchant by Two; a quarterly order with 4 instalments is repaid over 12 months." }, "number_of_instalments": { "description": "The number of instalments the order will be split into.", "exclusiveMinimum": 1, "title": "Number Of Instalments", "type": "integer" } }, "required": [ "period", "number_of_instalments" ], "title": "OrderInstalmentTerms", "type": "object" }, "OrderMerchantCallbackAuthSchema": { "properties": { "auth_type": { "$ref": "#/$defs/CallbackAuthTypeEnum" }, "value": { "title": "Value", "type": "string" } }, "required": [ "auth_type", "value" ], "title": "OrderMerchantCallbackAuthSchema", "type": "object" }, "OrderNetTerms": { "description": "By setting these fields, a merchant can create an net terms order with specified terms.", "properties": { "type": { "const": "NET_TERMS", "default": "NET_TERMS", "title": "Type", "type": "string" }, "duration_days": { "exclusiveMinimum": 0, "title": "Duration Days", "type": "integer" }, "duration_days_calculated_from": { "anyOf": [ { "$ref": "#/$defs/DueDateCalculationScheme" }, { "type": "null" } ], "default": null, "description": "Optional scheme for calculating the invoice due date. When set, modifies how due_in_days is calculated from the fulfillment date:\n- END_OF_MONTH: (days to end of month) + duration_days\n- END_OF_WEEK: (days to end of week, Sunday) + duration_days\nNote: Cannot be used with billing_account_id. Only specific duration_days values are allowed per scheme (typically 30, 45, 60)." } }, "required": [ "duration_days" ], "title": "OrderNetTerms", "type": "object" }, "OrderOriginationEnum": { "enum": [ "ONLINE", "IN_STORE" ], "title": "OrderOriginationEnum", "type": "string" }, "OrderTypeEnum": { "enum": [ "BUYER_INITIATED", "MERCHANT_INITIATED" ], "title": "OrderTypeEnum", "type": "string" }, "PaymentStatusEnum": { "enum": [ "NOT_PAID", "PAID", "PARTIAL_PAYMENT", "OVERDUE", "IN_COLLECTIONS", "CANCELLED", "REFUNDED", "PARTIAL_REFUND", "RECOURSED", "PARTIAL_RECOURSE" ], "title": "PaymentStatusEnum", "type": "string" }, "PeriodEnum": { "enum": [ "weekly", "biweekly", "monthly", "bimonthly", "quarterly", "yearly" ], "title": "PeriodEnum", "type": "string" }, "ProductDetailsSchema": { "properties": { "brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The brand name of the item. E.g. \"Heinz\".", "title": "Brand" }, "categories": { "description": "Array of one or more product categories. E.g. [\"Studio monitors\", \"Music equipment\"]", "items": { "type": "string" }, "title": "Categories", "type": "array" }, "barcodes": { "anyOf": [ { "items": { "$ref": "#/$defs/BarCodeSchema" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Array with Barcode objects for storing SKU, EAN, etc.", "title": "Barcodes" }, "part_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The manufacturer's part number", "title": "Part Number" } }, "required": [ "categories" ], "title": "ProductDetailsSchema", "type": "object" }, "RecurringDetailsSchema": { "properties": { "token": { "title": "Token", "type": "string" }, "description": { "title": "Description", "type": "string" }, "period": { "$ref": "#/$defs/PeriodEnum" } }, "required": [ "token", "description", "period" ], "title": "RecurringDetailsSchema", "type": "object" }, "ShippingDetailsSchema": { "properties": { "tracking_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tracking Number" }, "carrier_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Carrier Name" }, "carrier_tracking_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Carrier Tracking Url" }, "expected_delivery_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expected Delivery Date" }, "address_co": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Address Co" }, "address_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Address Reference" }, "address_attn": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Address Attn" }, "delivery_method": { "anyOf": [ { "$ref": "#/$defs/DeliveryMethodEnum" }, { "type": "null" } ], "default": null }, "id_required_on_delivery": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Id Required On Delivery" } }, "title": "ShippingDetailsSchema", "type": "object" }, "StrictRepresentativeSchema": { "properties": { "first_name": { "description": "Representative first name", "title": "First Name", "type": "string" }, "last_name": { "description": "Representative last name", "title": "Last Name", "type": "string" }, "phone_number": { "description": "Representative phone number. If the calling code is not provided, it automatically uses the calling code of the enum `country_prefix` in CompanySchema. However, you can also specify the calling code explicitly if it's for a different country. For instance, if the given phone number is 07807039055 and the buyer's `country_prefix` in CompanySchema is `GB`, the phone number is automatically converted to +447807039055. If the `country_prefix` in CompanySchema is `NO`, you can explicitly define a phone number for another country as +447807039055.", "title": "Phone Number", "type": "string" }, "email": { "description": "Representative email address", "format": "email", "title": "Email", "type": "string" } }, "required": [ "first_name", "last_name", "phone_number", "email" ], "title": "StrictRepresentativeSchema", "type": "object" }, "TaxSubtotalSchema": { "properties": { "tax_amount": { "description": "taxable_amount * tax rate", "format": "decimal", "pattern": "^-?[0-9]+(\\.[0-9]{0,2})?", "title": "Tax Amount", "type": "string" }, "taxable_amount": { "description": "sum(net_amount), per tax rate", "format": "decimal", "pattern": "^-?[0-9]+(\\.[0-9]{0,2})?", "title": "Taxable Amount", "type": "string" }, "tax_rate": { "description": "Must be between 0 and 1 inclusive", "format": "decimal", "pattern": "^-?[0-9]+(\\.[0-9]{0,6})?", "title": "Tax Rate", "type": "string" } }, "required": [ "tax_amount", "taxable_amount", "tax_rate" ], "title": "TaxSubtotalSchema", "type": "object" }, "TermsPeriod": { "enum": [ "MONTHLY", "QUARTERLY" ], "title": "TermsPeriod", "type": "string" } } }