> ## Documentation Index > Fetch the complete documentation index at: https://docs.voucherify.io/llms.txt > Use this file to discover all available pages before exploring further. # Import Orders > > 🚧 Historical orders > > This endpoint should only be used to import historical orders into Voucherify. For on-going synchronization, the [update order](/api-reference/orders/update-order) endpoint should be used. This is critical because this endpoint does not store events or launch distributions. The orders will also have a `created_at` date that's assigned when they've been imported to Voucherify. To keep track of the actual order creation date, add an order metadata in ISO 8601 date or date time format to each imported order. ## Limitations ### Import volume There can be only a single on-going order import per tenant per project at a given time. The user can schedule more imports but those extra imports will be scheduled to run in sequence one by one. ### Maximum count of orders in single import There is a `2000` limit of orders per one request. ## Notifications There are no notifications on the Dashboard because this import is launched via the API. ## Triggered actions If you import orders with customers, then a logic will be scheduled responsible for placing these customers into segments and refreshing the segment's summary. Consequently, this update will trigger - Customers entering into segments - Distributions based on any rules tied to customer entering segment(s) - Earning rules based on the customer entering segment(s) ## What is not triggered 1. No webhooks are triggered during the import of orders - for both orders and upserted products / SKUs. 2. Distributions based on Order Update, Order Paid, Order Created and Order Cancelled. In other words if you have a distribution based on Order Paid and you import an order with a `PAID` status, the distribution is not going to be triggered. 3. No events are created during the import of orders - for both orders and upserted products / SKUs. In other words you won't see any events in the Activity tab in the Dashboard such as Order created or Order paid. If you are additionally upserting products / SKUs, then you won't see the Product created events listed, etc. 4. Earning rules based on Order Paid won't be triggered. This API request starts a process that affects Voucherify data in bulk. In case of small jobs (like bulk update) the request is put into a queue and processed once every other bulk request placed in the queue prior to this request is finished. However, when the job takes a longer time (like vouchers generation) then it is processed in small portions in a round-robin fashion. When there is a list of vouchers generation scheduled, then they will all have the `IN_PROGRESS` status shortly. This way, small jobs added just after scheduling big jobs of the same type will be processed in a short time window. The result will return the async ID. You can verify the status of your request with [GET Async Action](/api-reference/async-actions/get-async-action) endpoint. ## OpenAPI ````yaml /openapi/orders.json post /v1/orders/import openapi: 3.0.1 info: title: Voucherify API - Orders version: v2018-08-01 description: >- Voucherify promotion engine REST API. Please see https://docs.voucherify.io/docs for more details. contact: name: Voucherify Team url: https://www.voucherify.io/contact-support email: support@voucherify.io termsOfService: https://www.voucherify.io/legal/subscription-agreement license: name: MIT url: https://github.com/voucherifyio/voucherify-js-sdk/blob/main/LICENSE servers: - url: https://{cluster}.voucherify.io description: Base URL variables: cluster: default: api enum: - api - us1.api - as1.api - download - us1.download - as1.download security: [] paths: /v1/orders/import: post: tags: - Orders summary: Import Orders description: >- > 🚧 Historical orders > > This endpoint should only be used to import historical orders into Voucherify. For on-going synchronization, the [update order](/api-reference/orders/update-order) endpoint should be used. This is critical because this endpoint does not store events or launch distributions. The orders will also have a `created_at` date that's assigned when they've been imported to Voucherify. To keep track of the actual order creation date, add an order metadata in ISO 8601 date or date time format to each imported order. ## Limitations ### Import volume There can be only a single on-going order import per tenant per project at a given time. The user can schedule more imports but those extra imports will be scheduled to run in sequence one by one. ### Maximum count of orders in single import There is a `2000` limit of orders per one request. ## Notifications There are no notifications on the Dashboard because this import is launched via the API. ## Triggered actions If you import orders with customers, then a logic will be scheduled responsible for placing these customers into segments and refreshing the segment's summary. Consequently, this update will trigger - Customers entering into segments - Distributions based on any rules tied to customer entering segment(s) - Earning rules based on the customer entering segment(s) ## What is not triggered 1. No webhooks are triggered during the import of orders - for both orders and upserted products / SKUs. 2. Distributions based on Order Update, Order Paid, Order Created and Order Cancelled. In other words if you have a distribution based on Order Paid and you import an order with a `PAID` status, the distribution is not going to be triggered. 3. No events are created during the import of orders - for both orders and upserted products / SKUs. In other words you won't see any events in the Activity tab in the Dashboard such as Order created or Order paid. If you are additionally upserting products / SKUs, then you won't see the Product created events listed, etc. 4. Earning rules based on Order Paid won't be triggered. This API request starts a process that affects Voucherify data in bulk. In case of small jobs (like bulk update) the request is put into a queue and processed once every other bulk request placed in the queue prior to this request is finished. However, when the job takes a longer time (like vouchers generation) then it is processed in small portions in a round-robin fashion. When there is a list of vouchers generation scheduled, then they will all have the `IN_PROGRESS` status shortly. This way, small jobs added just after scheduling big jobs of the same type will be processed in a short time window. The result will return the async ID. You can verify the status of your request with [GET Async Action](/api-reference/async-actions/get-async-action) endpoint. operationId: import-orders parameters: [] requestBody: description: The request body is sent in the form of an array of order objects. content: application/json: schema: $ref: '#/components/schemas/OrdersImportCreateRequestBody' examples: Example: value: - source_id: orderImport14 status: PAID metadata: location_id: - L1 - L2 payment_mean: - paypal - credit-card customer: source_id: bob2.smith@email.com name: Bob Smith description: A nice customer email: bob.smith@email.com phone: +1 933 222 3333 address: city: New York country: United States line_1: 123 Main St. line_2: APT 3 BLG 4 postal_code: '10001' state: NY metadata: lang: en test: true birthdate: '2022-01-01' referrer: source_id: jane.smith@email.com name: Jane Smith description: A really nice customer email: jane.smith@email.com phone: +1 933 222 3334 address: city: New York country: United States line_1: 123 Main St. line_2: APT 3 BLG 4 postal_code: '10001' state: NY metadata: lang: en test: false birthday: '2022-03-03' items: - source_id: prod_1 related_object: product quantity: 2 product: name: Apple iPhone 12 price: 70000 metadata: color: - silver vendor: mall override: true - source_id: ComicBook_1 related_object: sku quantity: 1 product: source_id: Books name: Comic Books1 price: 1600 metadata: color: - silver vendor: Bookstore1 override: true sku: sku: Comics1 source_id: ComicBook_1 price: 1600 metadata: color: - golden vendor: islands override: true - source_id: orderImport15 status: PAID metadata: location_id: - L3 payment_mean: - wire-transfer customer: source_id: bob2.smith@email.com referrer: source_id: jane.smith@email.com items: - source_id: ComicBook_1 quantity: 4 related_object: sku sku: source_id: ComicBook_1 - source_id: vase_1 quantity: 1 related_object: product product: source_id: vase_1 - source_id: orderImport16 status: FULFILLED metadata: location_id: - L3 payment_mean: - wire-transfer customer: id: cust_LMY4ZylSdUYB1J4tzqNcl5VV referrer: id: cust_Vzck5i8U3OhcEUFY6MKhN9Rv items: - product_id: prod_0b72b0bd64d198e3ae quantity: 2 - sku_id: sku_0b1621b319d248b79f quantity: 2 - source_id: orderImport17 status: CANCELED amount: 7000 metadata: location_id: - L3 payment_mean: - wire-transfer - source_id: orderImport18 status: CREATED metadata: location_id: - L3 payment_mean: - wire-transfer items: - source_id: ComicBook_1 amount: 900 related_object: sku - source_id: vase_1 amount: 2000 related_object: product - source_id: orderImport19 status: CREATED metadata: location_id: - L3 payment_mean: - wire-transfer items: - amount: 900 - amount: 2000 - source_id: orderImport20 status: CREATED metadata: location_id: - L3 payment_mean: - wire-transfer items: - price: 900 quantity: 2 - price: 2000 quantity: 3 required: true responses: '200': description: >- Returns the ID of the scheduled asynchronous action, informing you that your request has been accepted and the order(s) will be added to the repository asynchronously. To check the status and result, copy the `async_action_id` from the response and pass it using [Get Async Action](/api-reference/async-actions/get-async-action) endpoint. content: application/json: schema: $ref: '#/components/schemas/OrdersImportCreateResponseBody' examples: Example: value: async_action_id: aa_0a875d56c805df6601 '400': description: Returns an error if the payload is invalid. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid Payload: value: code: 400 key: invalid_payload message: Invalid payload details: Property .items[0].initial_quantity cannot be lower than 1 request_id: v-0c5561d945cb0f0fb5 security: - X-App-Id: [] X-App-Token: [] - X-Voucherify-OAuth: - api - orders components: schemas: OrdersImportCreateRequestBody: type: array title: Orders Import Create Request Body description: Request body schema for **POST** `/orders/import`. items: title: Orders Import Create Request Body Item type: object allOf: - $ref: '#/components/schemas/Order' - title: Order Customer And Referrer Ids Objects type: object description: Order information. properties: referrer_id: type: string nullable: true description: Unique referrer ID. example: cust_nM4jqPiaXUvQdVSA6vTRUnix customer: allOf: - $ref: '#/components/schemas/Customer' referrer: allOf: - $ref: '#/components/schemas/Referrer' OrdersImportCreateResponseBody: type: object title: Orders Import Create Response Body description: Response body schema for **POST** `v1/orders/import`. allOf: - $ref: '#/components/schemas/AsyncActions' Error: title: Error Object type: object description: Error details properties: code: type: integer description: Error's HTTP status code. key: type: string description: Short string describing the kind of error which occurred. message: type: string description: A human-readable message providing a short description of the error. details: type: string description: A human-readable message providing more details about the error. request_id: type: string example: v-0a885062c80375740f description: >- This ID is useful when troubleshooting and/or finding the root cause of an error response by our support team. resource_id: type: string description: >- Unique resource ID that can be used in another endpoint to get more details. example: rf_0c5d710a87c8a31f86 resource_type: type: string description: The resource type. example: voucher error: type: object description: Includes additional information about the error. properties: message: type: string description: The message configured by the user in a validation rule. required: - code - message Order: title: Order type: object description: Order information. allOf: - type: object properties: id: type: string description: >- Unique ID assigned by Voucherify of an existing order that will be linked to the redemption of this request. - $ref: '#/components/schemas/OrderBase' Customer: title: Customer allOf: - type: object title: Customer Id And Source Id properties: id: type: string description: The ID of an existing customer. source_id: type: string description: >- A unique identifier of the customer who validates a voucher. It can be a customer ID or email from a CRM system, database, or a third-party service. If you also pass a customer ID (unique ID assigned by Voucherify), the source ID will be ignored. - $ref: '#/components/schemas/CustomerBase' Referrer: title: Referrer allOf: - $ref: '#/components/schemas/Customer' AsyncActions: type: object title: Asynchronous Actions description: Response to requests that are processed asynchronously. properties: async_action_id: type: string example: aa_0a875d56c805df6601 description: The ID of the scheduled asynchronous action. required: - async_action_id OrderBase: title: Order Base type: object description: Order information. properties: source_id: type: string nullable: true description: >- Unique source ID of an existing order that will be linked to the redemption of this request. For validation and redemption, if `source_id` is used with an existing order, the original order data will be used, like `items`, `amount`, and so on, not the one sent in the new request. status: type: string description: The order status. enum: - CREATED - PAID - CANCELED - FULFILLED amount: type: integer description: >- A positive integer in the smallest currency unit (e.g. 100 cents for $1.00) representing the total amount of the order. This is the sum of the order items' amounts. initial_amount: type: integer description: >- A positive integer in the smallest currency unit (e.g. 100 cents for $1.00) representing the total amount of the order. This is the sum of the order items' amounts. discount_amount: type: integer description: >- Sum of all order-level discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00). items: type: array description: Array of items applied to the order. It can include up to 500 items. items: $ref: '#/components/schemas/OrderItem' metadata: type: object description: >- A set of custom key/value pairs that you can attach to an order. It can be useful for storing additional information about the order in a structured format. It can be used to define business validation rules or discount formulas. CustomerBase: title: Customer Base type: object properties: name: type: string description: Customer's first and last name. description: type: string description: An arbitrary string that you can attach to a customer object. email: type: string description: Customer's email address. phone: type: string description: >- Customer's phone number. This parameter is mandatory when you try to send out codes to customers via an SMS channel. birthday: type: string description: '`Deprecated`. ~~Customer''s birthdate; format YYYY-MM-DD~~.' format: date birthdate: type: string description: Customer's birthdate; format YYYY-MM-DD. format: date address: type: object nullable: true description: Customer's address. properties: city: type: string description: City state: type: string description: State line_1: type: string description: First line of address. line_2: type: string description: Second line of address. country: type: string description: Country. postal_code: type: string description: Postal code. metadata: type: object description: >- A set of custom key/value pairs that you can attach to a customer. The metadata object stores all custom attributes assigned to the customer. It can be useful for storing additional information about the customer in a structured format. This metadata can be used for validating whether the customer qualifies for a discount or it can be used in building customer segments. OrderItem: type: object title: Order Item properties: sku_id: type: string description: Unique identifier of the SKU. It is assigned by Voucherify. product_id: type: string description: Unique identifier of the product. It is assigned by Voucherify. related_object: type: string enum: - product - sku description: >- Used along with the source_id property, can be set to either sku or product. source_id: type: string description: >- The merchant's product/SKU ID (if it is different from the Voucherify product/SKU ID). It is useful in the integration between multiple systems. It can be an ID from an eCommerce site, a database, or a third-party service. quantity: type: integer description: The quantity of the particular item in the cart. discount_quantity: type: integer description: Number of dicounted items. initial_quantity: type: integer description: >- A positive integer in the smallest unit quantity representing the total amount of the order; this is the sum of the order items' quantity. amount: type: integer description: The total amount of the order item (price * quantity). discount_amount: type: integer description: Sum of all order-item-level discounts applied to the order. initial_amount: type: integer description: >- A positive integer in the smallest currency unit (e.g. 100 cents for $1.00) representing the total amount of the order. This is the sum of the order items' amounts. price: type: integer description: >- Unit price of an item. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`. product: type: object description: An object containing details of the related product. properties: id: type: string description: >- A unique identifier that represents the product and is assigned by Voucherify. source_id: type: string description: >- The merchant's product ID (if it is different than Voucherify's product ID). It is really useful in case of integration between multiple systems. It can be an ID from an eCommerce site, a database or a 3rd party service. override: type: boolean description: >- The override set to `true` is used to store the product information in the system. If the product does not exist, it will be created with a source_id; if it does exist, the provided values for the name, price, and metadata will replace those already stored in the system. Override works only for endpoints that create an order in the database. name: type: string description: Product name. metadata: type: object description: >- A set of custom key/value pairs that you can attach to a product. It can be useful for storing additional information about the product in a structured format. It can be used to create product collections. price: type: number description: >- Product price. A positive integer in the smallest currency unit (e.g. 100 cents for $1.00). sku: type: object description: An object containing details of the related SKU. properties: id: type: string description: >- A unique identifier that represents the SKU and is assigned by Voucherify. source_id: type: string description: >- The merchant's SKU ID (if it is different than Voucherify's SKU ID). It is really useful in case of integration between multiple systems. It can be an ID from an eCommerce site, a database or a 3rd party service. override: type: boolean description: >- The override set to `true` is used to store the product information in the system. If the product does not exist, it will be created with a source_id; if it does exist, the provided values for the name, price, and metadata will replace those already stored in the system. sku: type: string description: The SKU name. price: type: number description: >- SKU price. A positive integer in the smallest currency unit (e.g. 100 cents for $1.00). metadata: type: object description: >- A set of custom key/value pairs that you can attach to an order item. It can be useful for storing additional information about the order item in a structured format. It can be used to create product collections. metadata: type: object description: >- A set of custom key/value pairs that you can attach to an order item. It can be useful for storing additional information about the order item in a structured format. It can be used to define business validation rules. required: - object securitySchemes: X-App-Id: type: apiKey name: X-App-Id in: header X-App-Token: type: apiKey name: X-App-Token in: header X-Voucherify-OAuth: type: oauth2 flows: implicit: authorizationUrl: https://api.voucherify.io/v1/oauth/token scopes: api: Gives access to whole server-side API. vouchers: >- Gives access to all endpoints and methods starting with `v1/vouchers`. client_api: Gives access to whole client-side API. client_vouchers: >- Gives access to all endpoints and methods starting with `/client/v1/vouchers`. promotions: >- Gives access to all endpoints and methods starting with `/v1/promotions`. client_promotions: >- Gives access to all endpoints and methods starting with `/client/v1/promotions` campaigns: >- Gives access to all endpoints and methods starting with `v1/campaigns`. client_publish: >- Gives access to all endpoints and methods starting with `/client/v1/publish`. exports: >- Gives access to all endpoints and methods starting with `/v1/exports`. publications: >- Gives access to all endpoints and methods starting with `/v1/publications`. client_validate: >- Gives access to all endpoints and methods starting with `/client/v1/validate`. validations: >- Gives access to all endpoints and methods starting with `/v1/validations`. client_validations: >- Gives access to all endpoints and methods starting with `/client/v1/validations`. qualifications: >- Gives access to all endpoints and methods starting with `/v1/qualifications`. client_qualifications: >- Gives access to all endpoints and methods starting with `/client/v1/qualifications`. client_redeem: >- Gives access to all endpoints and methods starting with `/client/v1/redeem redemptions: >- Gives access to all endpoints and methods starting with `/v1/redemptions`. client_redemptions: >- Gives access to all endpoints and methods starting with `/client/v1/redemptions` customers: >- Gives access to all endpoints and methods starting with `/v1/customers`. client_customers: >- Gives access to all endpoints and methods starting with `/client/v1/customers`. orders: >- Gives access to all endpoints and methods starting with `/v1/orders`. products: >- Gives access to all endpoints and methods starting with `/v1/products`. skus: >- Gives access to all endpoints and methods starting with `/v1/SKUs`. validation-rules: >- Gives access to all endpoints and methods starting with `/v1/validation-rules`. validation-rules-assignments: >- Gives access to all endpoints and methods starting with `/v1/validation-rules-assignments segments: >- Gives access to all endpoints and methods starting with `/v1/segments`. events: >- Gives access to all endpoints and methods starting with `/v1/events`. client_events: >- Gives access to all endpoints and methods starting with `client/v1/events`. rewards: >- Gives access to all endpoints and methods starting with `/v1/rewards`. assets: >- Gives access to all endpoints and methods starting with `/v1/assets`. task-results: >- Gives access to all endpoints and methods starting with `/v1/task-results`. loyalties: >- Gives access to all endpoints and methods starting with `/v1/loyalties`. client_consents: >- Gives access to all endpoints and methods starting with `client/v1/consents`. consents: >- Gives access to all endpoints and methods starting with `/v1/consents`. async-actions: >- Gives access to all endpoints and methods starting with `/v1/async-actions`. product-collections: >- Gives access to all endpoints and methods starting with `/v1/product-collections`. categories: >- Gives access to all endpoints and methods starting with `/v1/categories`. metadata-schemas: >- Gives access to all endpoints and methods starting with `/v1/metadata-schemas`. locations: >- Gives access to all endpoints and methods starting with `/v1/locations`. referrals: >- Gives access to all endpoints and methods starting with `/v1/referrals`. trash-bin: >- Gives access to all endpoints and methods starting with `/v1/trash-bin`. templates: >- Gives access to all endpoints and methods starting with `/v1/templates`. ````