CreateOrderIntentRequestSchema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/two/json-schema/two-create-order-intent-request-schema-schema.json",
  "title": "CreateOrderIntentRequestSchema",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/two-openapi.yaml#/components/schemas/CreateOrderIntentRequestSchema",
  "properties": {
    "gross_amount": {
      "description": "net_amount + tax_amount",
      "format": "decimal",
      "pattern": "^-?[0-9]+(\\.[0-9]{0,2})?",
      "title": "Gross Amount",
      "type": "string"
    },
    "net_amount": {
      "anyOf": [
        {
          "format": "decimal",
          "pattern": "^-?[0-9]+(\\.[0-9]{0,2})?",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Net amount is optional but helpful for accurate assessment of order intents. If not provided, assessment will be conducted based on gross amount only.",
      "title": "Net Amount"
    },
    "tax_amount": {
      "anyOf": [
        {
          "format": "decimal",
          "pattern": "^-?[0-9]+(\\.[0-9]{0,2})?",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "net_amount * tax_rate",
      "title": "Tax Amount"
    },
    "invoice_type": {
      "anyOf": [
        {
          "$ref": "#/$defs/InvoiceTypeEnum"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "deprecated": true,
      "description": "FUNDED_INVOICE: Two will handle the invoice and transfer the funds to the merchant as per the factoring agreement. The invoice_details field will be populated by Two. DIRECT_INVOICE: Two generates and sends the invoice to the customer based on the bank account provided by the merchant, but the merchant takes the full credit and fraud risk on direct invoices and they will not receive a payout."
    },
    "currency": {
      "description": "Currency code in ISO 4217 format. E.g. 'NOK'",
      "title": "Currency",
      "type": "string"
    },
    "line_items": {
      "description": "List of the line items that constitute the order.",
      "items": {
        "$ref": "#/$defs/LineItemRequestSchema"
      },
      "title": "Line Items",
      "type": "array"
    },
    "buyer": {
      "anyOf": [
        {
          "$ref": "#/$defs/LaxRepBuyerSchema"
        },
        {
          "$ref": "#/$defs/SuperLaxRepBuyerSchema"
        },
        {
          "$ref": "#/$defs/BuyerSchemaForOrderIntentCreation"
        }
      ],
      "description": "Fields representing the buyer. Some elements are optional. Providing optional information enables a more accurate evaluation of the buyer.",
      "title": "Buyer"
    },
    "merchant_id": {
      "anyOf": [
        {
          "format": "uuid",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "A globally unique merchant ID set by Two.",
      "title": "Merchant Id"
    },
    "merchant_short_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "deprecated": true,
      "description": "Deprecated in favor of merchant_id.",
      "title": "Merchant Short Name"
    },
    "shipping_address": {
      "anyOf": [
        {
          "$ref": "#/$defs/CreateAddressRequestSchema"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Order shipping address. Optional. Providing this information enables a more accurate evaluation of the buyer."
    },
    "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."
    },
    "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": "The terms of this order",
      "title": "Terms"
    },
    "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": [
    "gross_amount",
    "currency",
    "line_items",
    "buyer"
  ],
  "type": "object",
  "$defs": {
    "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"
    },
    "BuyerSchemaForOrderIntentCreation": {
      "description": "A schema for specifying the buyer in an order intent. The user is encouraged to specify the buyer's company\nusing CompanyCanonicalIdSchema for unambiguous identification.",
      "properties": {
        "representative": {
          "anyOf": [
            {
              "$ref": "#/$defs/LaxRepresentativeSchema"
            },
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Fields to capture who the order is for",
          "title": "Representative"
        },
        "company": {
          "description": "Fields to capture the details of the company for which the order is intended. Users are encouraged to assign a CompanyFromCanonicalIdRequestSchema instance to this field using a canonical id retrieved from our company search API.",
          "oneOf": [
            {
              "$ref": "#/$defs/CompanyCanonicalIdSchema"
            },
            {
              "$ref": "#/$defs/CompanySchema"
            },
            {
              "type": "null"
            }
          ],
          "title": "Company"
        }
      },
      "required": [
        "company"
      ],
      "title": "BuyerSchemaForOrderIntentCreation",
      "type": "object"
    },
    "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"
    },
    "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"
    },
    "InvoiceTypeEnum": {
      "description": "Enumeration for invoice type.",
      "enum": [
        "FUNDED_INVOICE",
        "DIRECT_INVOICE",
        "CARD"
      ],
      "title": "InvoiceTypeEnum",
      "type": "string"
    },
    "LaxRepBuyerSchema": {
      "description": "A buyer schema variant used for creating order intents. It allows for an optional\nand less-strict `representative` (`LaxRepresentativeSchema`).\nThe company can be identified by full details (`CompanySchema`) or by `company_canonical_id`\n(`CompanyFromCanonicalIdSchema`).",
      "properties": {
        "representative": {
          "anyOf": [
            {
              "$ref": "#/$defs/LaxRepresentativeSchema"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Fields to capture who the order is for"
        },
        "company": {
          "$ref": "#/$defs/CompanySchema",
          "description": "Fields to capture the details of the company for which the order is intended"
        }
      },
      "required": [
        "company"
      ],
      "title": "LaxRepBuyerSchema",
      "type": "object"
    },
    "LaxRepresentativeSchema": {
      "description": "Relaxes validation on the representative's phone number by accepting a plain string\ninstead of enforcing the strict `PhoneNumberType` validation.",
      "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",
          "title": "Phone Number",
          "type": "string"
        },
        "email": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Representative email address",
          "title": "Email"
        }
      },
      "required": [
        "first_name",
        "last_name",
        "phone_number"
      ],
      "title": "LaxRepresentativeSchema",
      "type": "object"
    },
    "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"
    },
    "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"
    },
    "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"
    },
    "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"
    },
    "SuperLaxRepBuyerSchema": {
      "description": "Intended for use in create order intent request where the buyer might\nsend order intent with invalid representative data but it is okay for us to\nignore that entry and process the intent anyway.",
      "properties": {
        "representative": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Fields to capture who the order is for",
          "title": "Representative"
        },
        "company": {
          "$ref": "#/$defs/CompanySchema",
          "description": "Fields to capture the details of the company for which the order is intended"
        }
      },
      "required": [
        "company"
      ],
      "title": "SuperLaxRepBuyerSchema",
      "type": "object"
    },
    "TermsPeriod": {
      "enum": [
        "MONTHLY",
        "QUARTERLY"
      ],
      "title": "TermsPeriod",
      "type": "string"
    }
  }
}