> For the complete documentation index, see [llms.txt](https://docs.one-cp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.one-cp.com/integration-and-development/1-cp-corporate-checkout-api/corporate-checkout-schema.md).

# 📋 Corporate Checkout Schema

#### CorporateCheckout

This is the main object for creating a Corporate Checkout transaction. It includes all the information needed to process a transaction through the 1-CP platform.

| Property          | Type   | Required | Description                                                                                      |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| refIDs            | Map    | No       | External identifiers associated with the CorporateCheckout.                                      |
| title             | string | Yes      | Title of the CorporateCheckout.                                                                  |
| currency          | string | Yes      | Currency code for the CorporateCheckout.                                                         |
| items             | array  | Yes      | List of items included in the CorporateCheckout.                                                 |
| attachments       | array  | No       | List of attachments associated with the CorporateCheckout.                                       |
| note              | string | No       | Additional notes about the CorporateCheckout. (Internal note only - not visible to the customer) |
| email             | object | No       | Email content Subject and recipients which will receive the contract email.                      |
| restrictedMethods | array  | No       | Payment methods that the provider has deactivated                                                |

**Item Object**

This is the basic item properties:

<table><thead><tr><th width="176">Property</th><th width="166">Type</th><th width="90" data-type="checkbox">Required</th><th width="386">Description</th></tr></thead><tbody><tr><td>stockId</td><td>string</td><td>false</td><td>Extenal Stock identifier for the item.</td></tr><tr><td>name</td><td>string</td><td>true</td><td>Name of the item.</td></tr><tr><td>category</td><td>enum</td><td>true</td><td>Item Category.</td></tr><tr><td>description</td><td>string</td><td>false</td><td>Description of the item.</td></tr><tr><td>price</td><td>number</td><td>true</td><td>Price of the item.</td></tr><tr><td>quantity</td><td><a href="https://docs.one-cp.com/checkout-api#item-quantity-object">Quantity</a></td><td>true</td><td>Quantity details of the item.</td></tr><tr><td>totalTax</td><td>number</td><td>false</td><td>Total tax applicable to the item. This value will be calculated based on the <code>taxes</code> in case it is not provided(exp. 10)</td></tr><tr><td>total</td><td>number</td><td>false</td><td>Total cost of the item including taxes. This value will be calculated based on the taxes and the <code>price</code> in case it is not provided(exp. 1350)</td></tr><tr><td>taxes</td><td>array of <a href="https://docs.one-cp.com/checkout-api#item-tax-object">Tax</a></td><td>false</td><td>List of taxes applicable to the item</td></tr><tr><td>co2</td><td>number</td><td>false</td><td>Carbon dioxide pollution.</td></tr><tr><td>cancellationPolicy</td><td>CancellationPolicy</td><td>false</td><td>cancellation policy applicable to the item.</td></tr></tbody></table>

{% hint style="danger" %}
There are nine types of items that need additional properties in addition to the basic properties.
{% endhint %}

{% tabs %}
{% tab title="Accommodation" %}

<table><thead><tr><th width="183">Property</th><th width="94">Type</th><th width="79" data-type="checkbox">Required</th><th>Description</th></tr></thead><tbody><tr><td>period</td><td>Period</td><td>true</td><td>Time period for which the item is valid.</td></tr><tr><td>location</td><td>Location</td><td>true</td><td>Location address.</td></tr><tr><td>locationName</td><td>string</td><td>false</td><td>Location name (property name)</td></tr><tr><td>accommodationType</td><td>enum</td><td>true</td><td>AccommodationType</td></tr><tr><td>roomType</td><td>enum</td><td>false</td><td>RoomType</td></tr></tbody></table>
{% endtab %}

{% tab title="Rail" %}

<table><thead><tr><th width="141">Property</th><th width="99">Type</th><th width="102" data-type="checkbox">Required</th><th>Description</th></tr></thead><tbody><tr><td>period</td><td>Period</td><td>true</td><td>Time period for which the item is valid.</td></tr><tr><td>departure</td><td>Location</td><td>true</td><td>Location address.</td></tr><tr><td>destination</td><td>Location</td><td>true</td><td>Location address.</td></tr><tr><td>serviceClass</td><td>enum</td><td>true</td><td><code>FIRST_CLASS</code>, <code>BUSINESS_CLASS</code>, <code>ECONOMY_CLASS</code>, <code>OTHER</code></td></tr></tbody></table>
{% endtab %}

{% tab title="Rental car" %}

<table><thead><tr><th width="190">Property</th><th width="98">Type</th><th width="94" data-type="checkbox">Required</th><th>Description</th></tr></thead><tbody><tr><td>period</td><td>Period</td><td>true</td><td>Time period for which the item is valid.</td></tr><tr><td>pickUpLocation</td><td>Location</td><td>true</td><td>Pick-up location.</td></tr><tr><td>dropOffLocation</td><td>Location</td><td>true</td><td>Drop off location.</td></tr><tr><td>classificationCode</td><td>string</td><td>false</td><td>Classification code</td></tr></tbody></table>
{% endtab %}

{% tab title="Taxi shuttle" %}

<table><thead><tr><th width="172">Property</th><th width="101">Type</th><th width="89" data-type="checkbox">Required</th><th>Description</th></tr></thead><tbody><tr><td>period</td><td>Period</td><td>true</td><td>Time period for which the item is valid.</td></tr><tr><td>pickUpLocation</td><td>Location</td><td>true</td><td>Pick-up location.</td></tr><tr><td>dropOffLocation</td><td>Location</td><td>true</td><td>Drop off location.</td></tr></tbody></table>
{% endtab %}

{% tab title="Flight" %}

<table><thead><tr><th width="146">Property</th><th width="82">Type</th><th width="87" data-type="checkbox">Required</th><th>Description</th></tr></thead><tbody><tr><td>period</td><td>Period</td><td>true</td><td>Time period for which the item is valid.</td></tr><tr><td>flightNumber</td><td>string</td><td>false</td><td>Flight number.</td></tr><tr><td>departure</td><td>string</td><td>true</td><td>Departure - 3-letter IATA airport code. e.g. FRA</td></tr><tr><td>destination</td><td>string</td><td>true</td><td>Destination - 3-letter IATA airport code. e.g. MUC</td></tr><tr><td>airline</td><td>string</td><td>true</td><td>Airline - 3-letter ICAO or 2-letter IATA airline code. e.g. LH</td></tr><tr><td>serviceClass</td><td>enum</td><td>true</td><td><code>FIRST_CLASS</code>, <code>BUSINESS_CLASS</code>, <code>ECONOMY_CLASS</code>, <code>OTHER</code></td></tr><tr><td>fareClass</td><td>string</td><td>false</td><td>Fare class</td></tr></tbody></table>
{% endtab %}

{% tab title="Parking" %}

<table><thead><tr><th width="97">Property</th><th width="86">Type</th><th width="115">Required</th><th>Description</th><th data-hidden>Example</th><th data-hidden>Default value</th></tr></thead><tbody><tr><td>period</td><td>Period</td><td>true</td><td>Time period for which the item is valid.</td><td></td><td></td></tr><tr><td>location</td><td>Location</td><td>true</td><td>Location address.</td><td></td><td></td></tr><tr><td>plateNumber</td><td>string</td><td>false</td><td>Plate number of the car</td><td>433453</td><td></td></tr></tbody></table>
{% endtab %}

{% tab title="Other Travel" %}

<table><thead><tr><th width="97">Property</th><th width="86">Type</th><th width="115">Required</th><th>Description</th><th data-hidden>Example</th><th data-hidden>Default value</th></tr></thead><tbody><tr><td>period</td><td>Period</td><td></td><td>Time period for which the item is valid.</td><td></td><td></td></tr></tbody></table>
{% endtab %}

{% tab title="Travel Agency" %}

<table><thead><tr><th width="97">Property</th><th width="86">Type</th><th width="115">Required</th><th>Description</th><th data-hidden>Example</th><th data-hidden>Default value</th></tr></thead><tbody><tr><td>period</td><td>Period</td><td></td><td>Time period for which the item is valid.</td><td></td><td></td></tr></tbody></table>
{% endtab %}

{% tab title="Public Transportation" %}

<table><thead><tr><th width="97">Property</th><th width="86">Type</th><th width="115">Required</th><th>Description</th><th data-hidden>Example</th><th data-hidden>Default value</th></tr></thead><tbody><tr><td>period</td><td>Period</td><td></td><td>Time period for which the item is valid.</td><td></td><td></td></tr></tbody></table>
{% endtab %}
{% endtabs %}

{% hint style="info" %}
The items will be arranged in the order in which they appear. The first item is considered the main item.
{% endhint %}

#### Types

{% tabs %}
{% tab title="Category Type" %}

```
// Travel Categories
FLIGHT
RENTAL_CAR
TAXI_SHUTTLE
ACCOMMODATION
EVENT
SERVICE
PUBLIC_TRANSPORTATION
MICRO_MOBILITY
PARKING
FUEL
FEE
F_AND_B
OTHER
RAIL
CONFERENCE
TRAVEL_AGENCY
OTHER_TRAVEL

// Sales & Marketing Categories
ADVERTISING
MARKET_RESEARCH
CONFERENCE_NOT_TRAVEL
SUBSCRIPTION

// Research & Development Categories
LAP_SUPPLY
CONSULTING

// Technology & Subscriptions Categories
HARDWARE
SOFTWARE_AND_IT
SOFTWARE_SUBSCRIPTION
TELECOM

// General & Administrative Categories
OFFICE_SUPPLY
OFFICE_EQUIPMENT_AND_FURNITURE
RENT_AND_LEASE
UTILITIES
INSURANCE
LEGAL_FEE
ADMINISTRATIVE_SERVICE
RETAIL
```

{% endtab %}

{% tab title="Tax Type" %}

```
NET_PRICE
VAT
BED_TAX
CITY_HOTEL_FEES
COUNTRY_TAX
CITY_TAX
ENERGY_CHARGE
FEDERAL_TAX
GST
INCLUSION
LODGING_TAX
MAINTENANCE_FEE
OCCUPANCY_TAX
PACKAGE_RATE_FEE
ROOM_TAX
RESORT_FEES
SALES_TAX
STATE_PROVINCE_TAX
SURCHARGE
SERVICE_CHARGE
OTHER_TAX
TOURISM_TAX
```

{% endtab %}

{% tab title="Accommodation Type" %}

```
 RESORT
 HOSTEL
 HOTEL
 INN
 LODGE
 MOTEL
 LOVE_HOTEL
 KP_BUSINESS_HOTEL
 CAPSULE_HOTEL
 APARTMENT
 BED_BREAKFAST
 CAMPING
 CHALET
 BOAT
 FARM_STAY
 TENTED
 VILLA
 GUEST_HOUSE
 APART_HOTEL
 RIAD
 RYOKAN
 HOME_STAY
 HOLIDAY_HOME
 COUNTRY_HOUSE
 HOLIDAY_PARK
```

{% endtab %}

{% tab title="Room Type" %}

```
APARTMENT
QUADRUPLE
SUITE
TRIPLE
TWIN
DOUBLE
SINGLE
STUDIO
FAMILY
TWIN_DOUBLE
DORMITORY_ROOM
BEDINDORMITORY
BUNGALOW
CHALET
HOLIDAY_HOME
VILLA
MOBILE_HOME
TENT
```

{% endtab %}
{% endtabs %}

**Location Object**

<table><thead><tr><th width="119">Property</th><th width="91">Type</th><th width="99" data-type="checkbox">Required</th><th>Description</th></tr></thead><tbody><tr><td>street</td><td>string</td><td>false</td><td>Street name.</td></tr><tr><td>house</td><td>string</td><td>false</td><td>Number of Apartment.</td></tr><tr><td>zipCode</td><td>string</td><td>false</td><td>ZipCode.</td></tr><tr><td>city</td><td>string</td><td>true</td><td>City name.</td></tr><tr><td>country</td><td>string</td><td>true</td><td>Country name</td></tr><tr><td>lat</td><td>string</td><td>false</td><td>Latitude of the Location.</td></tr><tr><td>lng</td><td>string</td><td>false</td><td>Longitude of the Location.</td></tr></tbody></table>

{% hint style="danger" %}
Either street/house combination or latitude/longitude combination must be present
{% endhint %}

**Period Object**

<table><thead><tr><th width="111">Property</th><th width="98">Type</th><th width="89" data-type="checkbox">Required</th><th width="434">Description</th></tr></thead><tbody><tr><td>start</td><td>date time</td><td>false</td><td>Start Date/time using the ISO 8601 localized to the time zone at origin/ start.</td></tr><tr><td>end</td><td>date time</td><td>false</td><td>End Date/time using the ISO 8601 localized to the time zone at destination/ end.</td></tr></tbody></table>

**Item Quantity Object**

<table><thead><tr><th width="113">Property</th><th width="91">Type</th><th width="95" data-type="checkbox">Required</th><th width="492">Description</th></tr></thead><tbody><tr><td>amount</td><td>number</td><td>true</td><td>Amount of the quantity. Min is 1</td></tr><tr><td>unit</td><td>enum</td><td>false</td><td>Unit of the quantity : <code>FLAT_FEE</code>, <code>PER_HOUR</code>, <code>PER_DAY</code>, <code>PER_NIGHT</code>, <code>PER_WEEK</code>, <code>PER_MONTH</code>, <code>PER_YEAR</code>, <code>PER_PERSON</code> . Default value <code>FLAT_FEE</code></td></tr></tbody></table>

**Item Tax Object**

<table><thead><tr><th width="107">Property</th><th width="95">Type</th><th width="75" data-type="checkbox">Required</th><th width="504">Description</th></tr></thead><tbody><tr><td>type</td><td>enum</td><td>false</td><td>Type of the tax.see Tax type. Default <code>VAT</code></td></tr><tr><td>value</td><td>number</td><td>true</td><td>Value of the tax based on the unit used (if the unit provided is <code>AMOUNT</code>, we expect the value to be based on the currency used in the CorporateCheckout).</td></tr><tr><td>unit</td><td>enum</td><td>false</td><td>Unit of the tax value. <code>AMOUNT</code>, <code>PERCENT</code> . Default <code>PERCENT</code></td></tr><tr><td>basis</td><td>enum</td><td>false</td><td>Basis of the tax calculation: <code>FLAT_FEE</code>, <code>PER_QUANTITY</code>. Default <code>PER_QUANTITY</code></td></tr><tr><td>applyTo</td><td>enum</td><td>false</td><td>Indicates what the tax applies to. Tax type</td></tr></tbody></table>

**Attachment Object**

<table><thead><tr><th width="86">Property</th><th width="81">Type</th><th width="70" data-type="checkbox">Required</th><th width="512">Description</th></tr></thead><tbody><tr><td>url</td><td>string</td><td>false</td><td>URL to the file. (File size is limited to 10MB if uploaded to our system; otherwise, the URL must be publicly available and accessible at all times.)</td></tr><tr><td>type</td><td>string</td><td>false</td><td>Type of the attachment: <code>INVOICE</code>, <code>PROPOSAL</code>, <code>TERMS_CONDITIONS</code>, <code>PICTURES</code>, <code>HEADER_IMAGE</code>, <code>OTHER.</code></td></tr></tbody></table>

{% hint style="info" %}
The first image will be`HEADER_IMAGE`and the rest will be `PICTURES.`
{% endhint %}

**CheckoutEmail Object**

<table><thead><tr><th width="118">Property</th><th width="98">Type</th><th width="71" data-type="checkbox">Required</th><th>Description</th></tr></thead><tbody><tr><td>recipients</td><td>Recipient emails</td><td>true</td><td>List of recipients associated with the CorporateCheckout.</td></tr><tr><td>subject</td><td>string</td><td>true</td><td>The email subject that will be sent to the Recipient list.</td></tr><tr><td>content</td><td>string</td><td>true</td><td>The email content that will be sent to the Recipient list.</td></tr></tbody></table>

#### Payment Method Restriction

Merchant can declare which methods to disable when initializing a transaction. For example to restrict Visa and Klarna from use during contract checkout:

```
restrictedMethods: ['VIS', 'KLN']
```

| Payment Method Name | Payment Method Code |
| ------------------- | ------------------- |
| MasterCard          | ECA                 |
| Visa                | VIS                 |
| American Express    | AMX                 |
| China Union Pay     | CUP                 |
| Diners Club         | DIN                 |
| Discover            | DIS                 |
| JCB                 | JCB                 |
| EPS                 | EPS                 |
| iDEAL               | DEA                 |
| Klarna              | KLN                 |
| MobilePay           | MBP                 |
| PayPal              | PAP                 |
| BanContact          | BCN                 |
| Przelewy24          | P24                 |

**Set Up Cancellation of Item**

* The cancellationPolicy must be either a fully detailed object or a text.
* If sent item does not have a cancellation policy, the cancellation policy will be determined based on the configuration of the service provider company.
* If there are no applicable config for the service provider company, the policy will remain empty, and the items get created without a Cancellation Policy and Always refund the full amount (default 1-CP Policy will applied).
* Basically we have two reference date to do cancellation:
  1. Start period date (it is used with items that have a period property only)
  2. Payment date (it is used with all items)

you can determine the reference date through CancellationPolicy.reference property.

#### Cancellation Policy

<table><thead><tr><th width="134">Property</th><th width="151">Type</th><th width="93">Required</th><th>Description</th><th data-hidden>Example</th><th data-hidden>Default value</th></tr></thead><tbody><tr><td>description</td><td>string</td><td>no</td><td>Description of applicable penalty</td><td>"cancellation policy "</td><td>--</td></tr><tr><td>reference</td><td>enum</td><td>yes</td><td>Type of reference Enum: [PAYMENT_DATE, START_PERIOD]</td><td>PAYMENT_DATE</td><td>--</td></tr><tr><td>penalties</td><td>array of Penalty</td><td>yes</td><td>List of penalties applicable to the item.</td><td>--</td><td>--</td></tr></tbody></table>

#### Penalties types

* There are two models for determining the penalty:

1. DatePenalty: based on dates explicitly
2. OffsetPenalty: based on offsets relative to the reference

* The CancellationPolicy.penalties should be of one type, either DatePenalty or OffsetPenalty. Not both types together.

The API validates the penalties array when a cancellation policy is provided as an object:

* Do not mix `DATE_PENALTY` and `OFFSET_PENALTY` entries in the same array.
* For `DATE_PENALTY`, each penalty must have a unique `until` value.
* For `OFFSET_PENALTY`, each `amount` and `unit` combination must be unique, and the array may contain at most one offset with an amount of `0`.

If validation fails, the error identifies the item and field using the path `items.<index>.cancellationPolicy.penalties`.

#### DatePenalty

<table><thead><tr><th width="79">Property</th><th width="222">Type</th><th width="87">Required</th><th>Description</th><th data-hidden>Example</th><th data-hidden>Default value</th></tr></thead><tbody><tr><td>type</td><td>enum</td><td>yes</td><td>Type of Penalty Enum: [DATE_PENALTY]</td><td>DATE_PENALTY</td><td>--</td></tr><tr><td>value</td><td>CancellationPenaltyValue</td><td>yes</td><td>Value of Penalty</td><td>--</td><td>--</td></tr><tr><td>until</td><td>Date</td><td>yes</td><td>The date after which the penalty will be applied</td><td>2023-06-12T11:37:51.582Z</td><td>--</td></tr></tbody></table>

#### OffsetPenalty

<table><thead><tr><th width="101">Property</th><th width="224">Type</th><th width="90">Required</th><th>Description</th><th data-hidden>Example</th><th data-hidden>Default value</th></tr></thead><tbody><tr><td>type</td><td>enum</td><td>yes</td><td>Type of Penalty Enum: [OFFSET_PENALTY]</td><td>OFFSET_PENALTY</td><td>--</td></tr><tr><td>value</td><td>CancellationPenaltyValue</td><td>yes</td><td>Value of Penalty</td><td>--</td><td>--</td></tr><tr><td>offset</td><td>CancellationPenaltyOffset</td><td>yes</td><td>The time offset which will be applied</td><td>--</td><td>--</td></tr><tr><td>condition</td><td>string</td><td>no</td><td>Penalty Condition</td><td>"AFTER_PAYMENT"</td><td>--</td></tr></tbody></table>

#### CancellationPenaltyValue

<table><thead><tr><th width="93">Property</th><th width="101">Type</th><th width="93">Required</th><th>Description</th><th data-hidden>Example</th><th data-hidden>Default value</th></tr></thead><tbody><tr><td>amount</td><td>number</td><td>yes</td><td>Penalty amount</td><td>0</td><td>0</td></tr><tr><td>unit</td><td>enum</td><td>yes</td><td>Penalty value unit Enum: [FIXED_AMOUNT, PERCENTAGE]</td><td>FIXED_AMOUNT</td><td>--</td></tr></tbody></table>

#### CancellationPenaltyOffset

<table><thead><tr><th width="98">Property</th><th width="98">Type</th><th width="97">Required</th><th>Description</th><th data-hidden>Example</th><th data-hidden>Default value</th></tr></thead><tbody><tr><td>amount</td><td>number</td><td>yes</td><td>Penalty amount</td><td>2</td><td>0</td></tr><tr><td>unit</td><td>enum</td><td>yes</td><td>Penalty offset unit Enum:[DAYS, HOURS, MONTHS]</td><td>DAYS</td><td>--</td></tr></tbody></table>

**CancellationReq**

Request body for the cancel and refund endpoint.

| Property      | Type      | Required | Description                                                                                                             |
| ------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| contractId    | string    | Yes      | ID of the contract to cancel.                                                                                           |
| itemsOrder    | number\[] | Yes      | Array of item order numbers to cancel.                                                                                  |
| amount        | number    | No       | Specific refund amount. If not provided, the maximum refundable amount will be calculated based on cancellation policy. |
| invoiceNumber | string    | No       | Invoice number to associate with the cancellation.                                                                      |
| invoiceTitle  | string    | No       | Title of the invoice.                                                                                                   |

**ValidationError**

Describes the error response when request validation fails.

| Property   | Type                | Description                                  |
| ---------- | ------------------- | -------------------------------------------- |
| message    | string\[] \| string | Array of error messages or a single message. |
| error      | string              | General error type (e.g., "Bad Request").    |
| statusCode | number              | HTTP status code.                            |

#### Update Corporate checkout

Some properties of the Transaction can be updated to reflect changes such as title. These updates are restricted to specific fields to ensure the transaction’s consistency.

| Property    | Type   | Description                            | example               |
| ----------- | ------ | -------------------------------------- | --------------------- |
| title       | string | Title of the transaction.              | Booking               |
| note        | string | Note of the transaction.               | note text             |
| externalIds | object | External ids of the transaction        | { "sap\_id": "12345"} |
| attachments | object | Attachment associated with transaction | See attachment above  |