# Order API

## **Order requests**

| Filtering terms  | Description                                                                                   |
| ---------------- | --------------------------------------------------------------------------------------------- |
| `limit`          | Hits within a page (default: 100, maximum: 1000)                                              |
| `page`           | Number of the requested page (default: 0)                                                     |
| `wspyId`         | Internal ID, API returns it when an order is created                                          |
| `referenceId`    | External ID, the ID given when an order is created                                            |
| `referenceName`  | Order's name, the name given when an order is created                                         |
| `paymentStatus`  | Payment status (e.g.: `paid`, `pending`, etc.)                                                |
| `paymentGateway` | Method of payment (e.g.: `cod`, `card`, etc.)                                                 |
| `lastMod`        | Last modification's date. Lists even several created or modified orders after the given date. |

 Filtering terms listed above are linked with `AND` , you need to add only the terms that you'd like to filter. 

 In case of **XML**:

Url: `https://app.webshippy.com/wspyapi/GetOrder/xml`

Request:

```
<?xml version="1.0" encoding="utf-8"?>
<request>
  <apiKey>api-key-comes-here</apiKey>
  <page>0</page>
  <limit>10</limit>
  <filters>
    <wspyId></wspyId>
    <referenceId></referenceId>
    <referenceName></referenceName>
    <paymentStatus></paymentStatus>
    <paymentGateway></paymentGateway>
    <lastMod>2018-01-01 00:00:00</lastMod>
  </filters>
</request>
```

Response (example):

```
<?xml version="1.0" encoding="utf-8"?>
<response>
  <status>success</status>
  <message/>
  <result>
    <elem>
      <wspyId>176</wspyId>
      <status>fulfilled</status>
      <referenceId>87962-110037</referenceId>
      <referenceName>87962-110037</referenceName>
      <createdAt>2018-02-14 13:04:33</createdAt>
      <fulfilledAt>2018-02-20 16:27:17</fulfilledAt>
      <paymentGateway>cod</paymentGateway>
      <paymentStatus>pending</paymentStatus>
      <paymentTotalPrice>8940.00</paymentTotalPrice>
      <paymentTotalDiscounts>1000.00</paymentTotalDiscounts>
      <paymentCurrency>HUF</paymentCurrency>
      <shippingMode>GLS</shippingMode>
      <shippingPrice>1290.00</shippingPrice>
      <shippingVat>0.27</shippingVat>
      <paidAt/>
      <codAmount>1500.00</codAmount>
      <codCurrency>HUF</codCurrency>
      <codStatus/>
      <codReceivedAt/>
      <trackingCode>WSHPY176</trackingCode>
      <invoiceStatus/>
      <invoiceCreatedAt>2018-02-16 00:00:00</invoiceCreatedAt>
      <invoiceNo>inv#00001</invoiceNo>
      <refusedInvoiceNo/>
      <invoiceUrl/>
      <refusedDate/>
      <updatedAt>2018-02-26 12:18:17</updatedAt>
      <products>
        <elem>
          <sku>szuperhos-polo-piros-xl</sku>
          <productName>Szuperhős Póló</productName>
          <variantName>Piros, XL</variantName>
          <priceGross>1890.00</priceGross>
          <vat>0.27</vat>
          <quantity>3</quantity>
        </elem>
        <elem>
          <sku>cicanaci-one-size</sku>
          <productName>CicaNaci - One Size</productName>
          <variantName/>
          <priceGross>990.00</priceGross>
          <vat>0.27</vat>
          <quantity>1</quantity>
        </elem>
        <elem>
          <sku>akcios-sapka</sku>
          <productName>Akciós sapka</productName>
          <variantName>Fekete</variantName>
          <priceGross>1990.00</priceGross>
          <vat>0.27</vat>
          <quantity>1</quantity>
        </elem>
      </products>
    </elem>
    <elem>
      [ ... ]
    </elem>
    [ ... ]
  </result>
</response>
```

In case of a failed request (example):

```
<?xml version="1.0" encoding="utf-8"?>
<response>
  <status>error</status>
  <message>
    <elem>[field: lastMod]The field must be a valid datetime (eg. yyyy-mm-dd hh:ii:ss)</elem>
  </message>
</response>
```

In case of **JSON**:

Url: `https://app.webshippy.com/wspyapi/GetOrder/json`

Request:

```
{
  "apiKey": "api-key-comes-here",
  "page": "0",
  "limit": "10",
  "filters": {
    "wspyId": "",
    "referenceId": "",
    "referenceName": "",
    "paymentStatus": "",
    "paymentGateway": "",
    "lastMod": "2018-01-01 00:00:00"
  }
}
```

Response (example):

```
{
  "status": "success",
  "message": [],
  "result": [
    {
      "wspyId": "176",
      "status": "fulfilled",
      "referenceId": "87962-110037",
      "referenceName": "87962-110037",
      "createdAt": "2018-02-14 13:04:33",
      "fulfilledAt": "2018-02-20 16:27:17",
      "paymentGateway": "cod",
      "paymentStatus": "pending",
      "paymentTotalPrice": "8940.00",
      "paymentTotalDiscounts": "1000.00",
      "paymentCurrency": "HUF",
      "shippingMode": "GLS",
      "shippingPrice": "1290.00",
      "shippingVat": "0.27",
      "paidAt": null,
      "codAmount": "1500.00",
      "codCurrency": "HUF",
      "codStatus": "",
      "codReceivedAt": null,
      "trackingCode": "WSHPY176",
      "invoiceStatus": "",
      "invoiceCreatedAt": "2018-02-16 00:00:00",
      "invoiceNo": "inv#00001",
      "refusedInvoiceNo": null,
      "invoiceUrl": null,
      "refusedDate": null,
      "updatedAt": "2018-02-26 12:18:17",
      "products": [
        {
          "sku": "szuperhos-polo-piros-xl",
          "productName": "Szuperhős Póló",
          "variantName": "Piros, XL",
          "priceGross": "1890.00",
          "vat": "0.27",
          "quantity": "3"
        },
        {
          "sku": "cicanaci-one-size",
          "productName": "CicaNaci - One Size",
          "variantName": null,
          "priceGross": "990.00",
          "vat": "0.27",
          "quantity": "1"
        },
        {
          "sku": "akcios-sapka",
          "productName": "Akciós sapka",
          "variantName": "Fekete",
          "priceGross": "1990.00",
          "vat": "0.27",
          "quantity": "1"
        }
      ]
    },
    {
      [ ... ]
    }
  ]
}
```

In case of a failed request (example):

```
{
  "status": "error",
  "message": [
    "[field: lastMod]The field must be a valid datetime (eg. yyyy-mm-dd hh:ii:ss)"
  ]
}
```

| Field              | Description                                                                                                                                                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `status`           | Action's result. Possible values: `success`, `error`                                                                                                                                                                           |
| `message`          | Error messages are in this field in case of a failed request                                                                                                                                                                   |
| `result`           | Results of a successful request are in this field as a block in each case                                                                                                                                                      |
| `wspyId`           | The Internal ID, API returns it when an order is created                                                                                                                                                                       |
| `status`           | <p>Order's status, possible values:<br><code>new</code>: New<br><code>draft</code>: Draft<br><code>ready</code>: Ready<br><code>packing</code>: Packing<br><code>fulfilled</code>: Packed<br><code>refused</code>: Refused</p> |
| `referenceId`      | External ID, the ID given when an order is created                                                                                                                                                                             |
| `referenceName`    | Order's name, the name given when an order is created                                                                                                                                                                          |
| `createdAt`        | (Original) time when the order got created                                                                                                                                                                                     |
| `fulfilledAt`      | Time when the order got packed                                                                                                                                                                                                 |
| `paymentStatus`    | Payment status                                                                                                                                                                                                                 |
| `paidAt`           | In case it is paid, the time of payment                                                                                                                                                                                        |
| `codAmount`        | Amount of Cash On Delivery                                                                                                                                                                                                     |
| `codCurrency`      | Currency of Cash On Delivery                                                                                                                                                                                                   |
| `codStatus`        | Status of Cash On Delivery                                                                                                                                                                                                     |
| `codReceivedAt`    | When the Cash On Delivery got recieved                                                                                                                                                                                         |
| `trackingCode`     | Tracking code of the courier service                                                                                                                                                                                           |
| `invoiceUrl`       | Invoice link to download ([https://example.com/invoice.pdf](http://example.com/invoice.pdf))                                                                                                                                   |
| `invoiceStatus`    | <p>Invoice status<br><code>uninvoiced</code>: Not yet invoiced<br><code>invoiced</code>: Invoiced<br><code>storno</code>: Canceled</p>                                                                                         |
| `invoiceCreatedAt` | Time when the invoice got created                                                                                                                                                                                              |
| `invoiceNo`        | ID number of invoice                                                                                                                                                                                                           |
| `refusedInvoiceNo` | Canceled invoice's ID number                                                                                                                                                                                                   |
| `refusedDate`      | Time of package return, and date of canceled invoice                                                                                                                                                                           |
| `updatedAt`        | Date of last modification in our system                                                                                                                                                                                        |
| `products`         | Products in an order, only in block form                                                                                                                                                                                       |
| `sku`              | Product's SKU, item number                                                                                                                                                                                                     |
| `productName`      | Product's name                                                                                                                                                                                                                 |
| `variantName`      | Product variant name                                                                                                                                                                                                           |
| `priceGross`       | Product's gross selling price                                                                                                                                                                                                  |
| `vat`              | VAT key                                                                                                                                                                                                                        |
| `quantity`         | Ordered quantity                                                                                                                                                                                                               |
| `serial`           | Unique identifier affixed to the product at the time of packaging (optional)                                                                                                                                                   |

## **Generating and modifying orders**

With this function you can create and modify your orders. In case the order does not have a `referenceId`, the API will generate one. In case you do have, and the status of the existing order is new, or draft, or there has not been manual modification, then the API modifies it. In case of a successful generation or modification, API gives back the order's Internal ID.

<table data-header-hidden><thead><tr><th>Field</th><th width="106.33333333333331">Required?</th><th>Description</th></tr></thead><tbody><tr><td>Field</td><td>Required?</td><td>Description</td></tr><tr><td><code>apiKey</code></td><td>Yes</td><td>API key</td></tr><tr><td><code>order</code></td><td>Yes</td><td>Order's details in generation or modification</td></tr><tr><td><code>referenceId</code></td><td>Yes</td><td><p>External ID, free word, recommended to use the order's ID</p><p></p></td></tr><tr><td><code>referenceName</code></td><td>No</td><td>Order name, free word, recommended to use the order's ID or a name created with it, for example <code>ORDER#1221</code></td></tr><tr><td><code>createdAt</code></td><td>Yes</td><td>Time of order's creation</td></tr><tr><td><code>shipping</code></td><td>Yes</td><td>Delivery data</td></tr><tr><td><code>shipping.name</code></td><td>Yes</td><td>Recipient's name</td></tr><tr><td><code>shipping.company</code></td><td>No</td><td>Company name</td></tr><tr><td><code>shipping.email</code></td><td>No</td><td>E-mail address</td></tr><tr><td><code>shipping.phone</code></td><td>No</td><td>Phone number</td></tr><tr><td><code>shipping.countryCode</code></td><td>Yes</td><td>Two-digit country code (e.g.: <code>HU</code>)</td></tr><tr><td><code>shipping.stateOrProvinceCode</code></td><td>No</td><td>State, Province ( especially when addressed abroad)</td></tr><tr><td><code>shipping.zip</code></td><td>Yes</td><td>Post code</td></tr><tr><td><code>shipping.city</code></td><td>Yes</td><td>City</td></tr><tr><td><code>shipping.address1</code></td><td>Yes</td><td>First line of address</td></tr><tr><td><code>shipping.address2</code></td><td>No</td><td>Second line of address</td></tr><tr><td><code>shipping.note</code></td><td>No</td><td>Title's note, use of <code>&#x3C;![CDATA[]]></code> recommended</td></tr><tr><td><code>shipping.mode</code></td><td>No</td><td><p>Transfer method, possible values: </p><ul><li><code>GLS-HU</code>,</li><li><code>DPD-HU,</code></li><li><code>FOXPOST-HU</code>,</li><li><code>DHL</code>,</li><li><code>SPRINTER</code>,</li><li><code>CSOMAGKULDO-HU</code></li><li><code>MPL.</code></li></ul></td></tr><tr><td><code>shipping.packPoint</code></td><td>No</td><td><p>Type of Pack point, possible values: </p><ul><li><code>GLS-HU</code>,</li><li><code>DPD-HU,</code></li><li><code>FOXPOST-HU</code>,</li><li><code>SPRINTER</code>,</li><li><code>CSOMAGKULDO-HU</code></li><li><code>MPL,</code></li><li><code>EUSHIPMENTS-328-ROMANIA-SAMEDAY,</code></li><li><code>EUSHIPMENTS-643-POLAND-INPOST-LOCKERS,</code></li><li><code>EUSHIPMENTS-722-CROATIA-GLS-LOCKERS,</code></li><li><code>EUSHIPMENTS-15-BULGARIA-ECONT.</code></li></ul></td></tr><tr><td><code>shipping.packPointId</code></td><td>No</td><td>Pack point's ID</td></tr><tr><td><code>billing</code></td><td>No*</td><td>Billing data, requested when we invoice</td></tr><tr><td><code>billing.name</code></td><td>Yes</td><td>Invoice name</td></tr><tr><td><code>billing.company</code></td><td>No</td><td>Company name</td></tr><tr><td><code>billing.taxNumber</code></td><td>No</td><td>Tax number</td></tr><tr><td><code>billing.phone</code></td><td>No</td><td>Phone number</td></tr><tr><td><code>billing.countryCode</code></td><td>Yes</td><td>Two-digit country code (e.g.: <code>HU</code>)</td></tr><tr><td><code>billing.zip</code></td><td>Yes</td><td>Post code</td></tr><tr><td><code>billing.city</code></td><td>Yes</td><td>City</td></tr><tr><td><code>billing.address1</code></td><td>Yes</td><td>First line of address</td></tr><tr><td><code>billing.address2</code></td><td>No</td><td>Second line of address</td></tr><tr><td><code>payment</code></td><td>Yes</td><td>Information about payment</td></tr><tr><td><code>payment.paymentMode</code></td><td>Yes</td><td>Payment method, uses smart surveying, recommended values:  <code>cod</code>, <code>card</code>, <code>paypal</code>, etc.</td></tr><tr><td><code>payment.codAmount</code></td><td>No</td><td>Amount of Cash On Delivery, may differ from total, courier recieves it as COD amount</td></tr><tr><td><code>payment.paymentStatus</code></td><td>Yes</td><td>Payment status, possible values: <code>paid</code>, <code>pending</code>. Other cases require consultation</td></tr><tr><td><code>payment.paidDate</code></td><td>No*</td><td>Date of payment, reuired if the status is paid</td></tr><tr><td><code>payment.shippingPrice</code></td><td>No</td><td>Price of delivery fee (Gross)</td></tr><tr><td><code>payment.shippingVat</code></td><td>No</td><td>Price of delivery fee's VAT key</td></tr><tr><td><code>payment.currency</code></td><td>Yes</td><td>Currency of order, three-digit (ISO) ID e.g.: <code>HUF</code> </td></tr><tr><td><code>payment.discount</code></td><td>No</td><td>Discount from Total</td></tr><tr><td><code>products</code></td><td>No</td><td>Products in the Order</td></tr><tr><td><code>products.sku</code></td><td>Yes</td><td>Product's SKU, item number</td></tr><tr><td><code>products.productName</code></td><td>Yes</td><td>Product's name</td></tr><tr><td><code>products.variantName</code></td><td>No</td><td>Product variant name</td></tr><tr><td><code>products.priceGross</code></td><td>Yes</td><td>Product's gross selling price</td></tr><tr><td><code>products.vat</code></td><td>Yes</td><td>VAT key</td></tr><tr><td><code>products.quantity</code></td><td>Yes</td><td>Ordered quantity</td></tr><tr><td><code>invoiceUrl</code></td><td>No</td><td><p>Invoice link to download (<a href="http://example.com/invoice.pdf">https://example.com/invoice.pdf</a>) </p><p><code>Required when API connection has Manual PDF invoice system (in this case the system uses it)</code> </p></td></tr><tr><td><code>pdfSource</code></td><td>No</td><td><p>PDF format invoice file with base64 coding</p><p><code>Required when API connection has Manual PDF invoice system</code></p></td></tr></tbody></table>

In case of **XML**:

Url: `https://app.webshippy.com/wspyapi/CreateOrder/xml`

Request:

```
<?xml version="1.0" encoding="utf-8"?>
<request>
  <apiKey>api-key-comes-here</apiKey>
  <order>
    <referenceId>87962-110037</referenceId>
    <referenceName>87962-110037</referenceName>
    <createdAt>2018-02-14 13:04:33</createdAt>
    <shipping>
      <name>Kováts Béla</name>
      <company>Virág Bt.</company>
      <email>bela@viragbt.hu</email>
      <phone>+36301234567</phone>
      <countryCode>HU</countryCode>
      <stateOrProvinceCode></stateOrProvinceCode>
      <zip>1234</zip>
      <city>Budapest</city>
      <address1>Virág utca 25.</address1>
      <address2></address2>
      <note><![CDATA[Szállításkor kérem a futárt, hogy ne csengessen!!!]]></note>
      <mode>GLS</mode>
    </shipping>
    <billing>
      <name>Kováts Béla</name>
      <company>Virág Bt.</company>
      <phone>+36301234567</phone>
      <countryCode>HU</countryCode>
      <zip>1234</zip>
      <city>Budapest</city>
      <address1>Virág utca 25.</address1>
      <address2></address2>
    </billing>
    <payment>
      <paymentMode>COD</paymentMode>
      <codAmount>1500.00</codAmount>
      <paymentStatus>pending</paymentStatus>
      <paidDate></paidDate>
      <shippingPrice>1290.00</shippingPrice>
      <shippingVat>0.27</shippingVat>
      <currency>HUF</currency>
      <discount>1000.00</discount>
    </payment>
    <products>
      <elem>
        <sku>szuperhos-polo-piros-xl</sku>
        <productName>Szuperhős Póló</productName>
        <variantName>Piros, XL</variantName>
        <priceGross>1890.00</priceGross>
        <vat>0.27</vat>
        <quantity>3</quantity>
      </elem>
      <elem>
        <sku>cicanaci-one-size</sku>
        <productName>CicaNaci - One Size</productName>
        <priceGross>990.00</priceGross>
        <vat>0.27</vat>
        <quantity>1</quantity>
      </elem>
      <elem>
        <sku>akcios-sapka</sku>
        <productName>Akciós sapka</productName>
        <variantName>Fekete</variantName>
        <priceGross>1990.00</priceGross>
        <vat>0.27</vat>
        <quantity>1</quantity>
      </elem>
    </products>
  </order>
</request>
```

Response (example):

```
<?xml version="1.0" encoding="utf-8"?>
<response>
  <status>success</status>
  <message>
    <elem>The order creation was successful</elem>
  </message>
  <wspyId>176</wspyId>
</response>
```

In case of **JSON**:

Url: `https://app.webshippy.com/wspyapi/CreateOrder/json`

Request:

```
{
  "apiKey": "api-key-comes-here",
  "order": {
    "referenceId": "87962-110037",
    "referenceName": "87962-110037",
    "createdAt": "2018-02-14 13:04:33",
    "shipping": {
      "name": "Kov\u00e1ts B\u00e9la",
      "company": "Vir\u00e1g Bt.",
      "email": "bela@viragbt.hu",
      "phone": "+36301234567",
      "countryCode": "HU",
      "stateOrProvinceCode": "",
      "zip": "1234",
      "city": "Budapest",
      "address1": "Vir\u00e1g utca 25.",
      "address2": "",
      "note": "",
      "mode": "GLS"
    },
    "billing": {
      "name": "Kov\u00e1ts B\u00e9la",
      "company": "Vir\u00e1g Bt.",
      "phone": "+36301234567",
      "countryCode": "HU",
      "zip": "1234",
      "city": "Budapest",
      "address1": "Vir\u00e1g utca 25.",
      "address2": ""
    },
    "payment": {
      "paymentMode": "COD",
      "codAmount": "1500.00",
      "paymentStatus": "pending",
      "paidDate": "",
      "shippingPrice": "1290.00",
      "shippingVat": "0.27",
      "currency": "HUF",
      "discount": "1000.00"
    },
    "products": [
      {
        "sku": "szuperhos-polo-piros-xl",
        "productName": "Szuperh\u0151s P\u00f3l\u00f3",
        "variantName": "Piros, XL",
        "priceGross": "1890.00",
        "vat": "0.27",
        "quantity": "3"
      },
      {
        "sku": "cicanaci-one-size",
        "productName": "CicaNaci - One Size",
        "priceGross": "990.00",
        "vat": "0.27",
        "quantity": "1"
      },
      {
        "sku": "akcios-sapka",
        "productName": "Akci\u00f3s sapka",
        "variantName": "Fekete",
        "priceGross": "1990.00",
        "vat": "0.27",
        "quantity": "1"
      }
    ]
  }
}
```

Response (example):

```
{
  "status": "success",
  "message": [
    "The order creation was successful"
  ],
  "wspyId": 176
}
```

Additional response possibilities:

* `The order creation was successful`
* `The order modification was successful`

## **Order's delete**

In case of **JSON**:

Url: `https://app.webshippy.com/wspyapi/deleteOrder/json`

Request:

```
{
  "apiKey": "api-key-comes-here",
  "filters": {
    "wspyId": "917872738"
  }
}
```

**I**n case of **XML**:

Url: `https://app.webshippy.com/wspyapi/deleteOrder/xml`

Request:

```
<?xml version="1.0" encoding="utf-8"?>
<request>
 <apiKey>api-key-comes-here</apiKey>
 <filters>
    <wspyId>917872738</wspyId>
  </filters>
</request>
```

| Filtering terms | Description                                              |
| --------------- | -------------------------------------------------------- |
| `wspyId`        | The Internal ID, API returns it when an order is created |
| `referenceId`   | External ID, the ID given when an order is created       |
| `referenceName` | Order's name, the name given when an order is created    |

{% hint style="info" %}
Only one order can be deleted at a time! An order which has been manually modified by a user in Webshippy can not be deleted with API request.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://www.apidoc-en.webshippy.com/webshippy-api-guide/order-related-functions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.