Order Resource

Order Resource

Attention

Order resources are read-only by default. Please contact us for access.



Order Statuses

Order Status
English
German
open
new order
Neue Bestellung
in_progress
in progress, started processing
Bearbeitung begonnen
cancelled
order was cancelled
Bestellung storniert
closed
order is sent and paid
Versandt und bezahlt
returned
order was returned to seller
Bestellung zurückgegeben



Get Orders

GET /api/orders.json

  • GET /api/orders.json will return the first 150 (default limit) orders. You can increase the limit to a maximum of 250 orders. See the Filter Orders endpoint for more info.

Example:

$ curl -s \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u APP_API_KEY:APP_API_PASSWORD \
-X GET \
http://shop_subdomain.versacommerce.de/api/orders.json

Status: 200 OK

[
  {
    "order": {
      "bank_account_bank_code": null,
      "bank_account_bank_name": null,
      "bank_account_name": null,
      "bank_account_number": null,
      "checkout_locale": "de",
      "code": "196-083-565",
      "coupon_code": null,
      "coupon_value": "0.0",
      "created_at": "2013-03-19T12 =>39 =>51+01 =>00",
      "currency": "€",
      "customer_email": "support@versacommerce.de",
      "customer_id": 1000,
      "discount_total": "0.0",
      "external_invoicing_id": null,
      "id": 100,
      "item_total": "8.49",
      "items_count": 1,
      "items_status": "undelivered",
      "note": "Lorem ipsum dolor sit amet...",
      "payment_cost": "2.5",
      "payment_status": "not_paid",
      "payment_tax_rate": 19,
      "payment_type": "cod",
      "payments_count": 0,
      "prices_include_tax": true,
      "reduced_tax_amount": "0.0",
      "reduced_tax_rate": 7,
      "reduced_tax_total": "0.0",
      "referrer": "/",
      "shipments_count": 0,
      "shipping_cost": "4.95",
      "shop_id": 953,
      "source": null,
      "standard_tax_amount": "2.55",
      "standard_tax_rate": 19,
      "standard_tax_total": "15.94",
      "status": "canceled",
      "subtotal": "15.94",
      "total": "15.94",
      "weight_total": 0,
      "shipping_address": {
        "category": "shipping",
        "city": "Welver",
        "company": "VersaCommerce",
        "country": "DE",
        "customer_id": 1000,
        "email": "support@versacommerce.de",
        "extension": "",
        "firstname": "Eduard",
        "id": 10000,
        "lastname": "Siebert",
        "locked": true,
        "option_01": "",
        "option_02": "",
        "option_03": "",
        "order_id": 100,
        "phone": "+49 511 1659 800",
        "state": "unbekannt",
        "street": "Zwischen Den Hölzern",
        "streetnumber": "1a",
        "title": "Herr",
        "zipcode": "59514"
      },
      "billing_address": {
        "category": "billing",
        "city": "Welver",
        "company": "VersaCommerce",
        "country": "DE",
        "customer_id": 1000,
        "email": "support@versacommerce.de",
        "extension": "",
        "firstname": "Eduard",
        "id": 10001,
        "lastname": "Siebert",
        "locked": true,
        "option_01": "",
        "option_02": "",
        "option_03": "",
        "order_id": 100,
        "phone": "+49 511 1659 800",
        "state": "unbekannt",
        "street": "Zwischen Den Hölzern",
        "streetnumber": "1a",
        "title": "Herr",
        "zipcode": "59514"
      },
      "customer": {
        "accepts_newsletter": false,
        "account_confirmation_sent": false,
        "active": true,
        "birthday": null,
        "created_on": "2012-11-09",
        "email": "support@versacommerce.de",
        "id": 1000,
        "note": null,
        "option_01": "",
        "option_02": "",
        "option_03": "",
        "option_04": "",
        "registered": true,
        "shop_id": 953,
        "updated_on": "2012-11-09"
      }
    }
  },
  {
    "order": {
      "bank_account_bank_code": null,
      "bank_account_bank_name": null,
      "bank_account_name": null,
      "bank_account_number": null,
      "checkout_locale": "de",
      "code": "196-083-545",
      "coupon_code": null,
      "coupon_value": "0.0",
      "created_at": "2013-03-19T12 =>41 =>47+01 =>00",
      "currency": "€",
      "customer_email": "siebert@versacommerce.de",
      "customer_id": 11461,
      "discount_total": "0.0",
      "external_invoicing_id": null,
      "id": 101,
      "item_total": "90.0",
      "items_count": 1,
      "items_status": "undelivered",
      "note": "Lorem ipsum dolor sit amet...",
      "payment_cost": "2.5",
      "payment_status": "not_paid",
      "payment_tax_rate": 19,
      "payment_type": "cod",
      "payments_count": 0,
      "prices_include_tax": true,
      "reduced_tax_amount": "0.0",
      "reduced_tax_rate": 7,
      "reduced_tax_total": "0.0",
      "referrer": "/",
      "shipments_count": 0,
      "shipping_cost": "4.95",
      "shop_id": 953,
      "source": null,
      "standard_tax_amount": "15.56",
      "standard_tax_rate": 19,
      "standard_tax_total": "97.45",
      "status": "canceled",
      "subtotal": "97.45",
      "total": "97.45",
      "weight_total": 0,
      "shipping_address": {
        "category": "shipping",
        "city": "Welver",
        "company": "VersaCommerce",
        "country": "DE",
        "customer_id": 1000,
        "email": "support@versacommerce.de",
        "extension": "",
        "firstname": "Eduard",
        "id": 10002,
        "lastname": "Siebert",
        "locked": true,
        "option_01": "",
        "option_02": "",
        "option_03": "",
        "order_id": 101,
        "phone": "+49 511 1659 800",
        "state": "unbekannt",
        "street": "Zwischen Den Hölzern",
        "streetnumber": "1a",
        "title": "Herr",
        "zipcode": "59514"
      },
      "billing_address": {
        "category": "billing",
        "city": "Welver",
        "company": "VersaCommerce",
        "country": "DE",
        "customer_id": 1000,
        "email": "support@versacommerce.de",
        "extension": "",
        "firstname": "Eduard",
        "id": 10003,
        "lastname": "Siebert",
        "locked": true,
        "option_01": "",
        "option_02": "",
        "option_03": "",
        "order_id": 101,
        "phone": "+49 511 1659 800",
        "state": "unbekannt",
        "street": "Zwischen Den Hölzern",
        "streetnumber": "1a",
        "title": "Herr",
        "zipcode": "59514"
      },
      "customer": {
        "accepts_newsletter": false,
        "account_confirmation_sent": false,
        "active": true,
        "birthday": null,
        "created_on": "2012-11-09",
        "email": "support@versacommerce.de",
        "id": 1000,
        "note": null,
        "option_01": "",
        "option_02": "",
        "option_03": "",
        "option_04": "",
        "registered": true,
        "shop_id": 953,
        "updated_on": "2012-11-09"
      }
    }
  }
]


Get Order

GET /api/orders/:order_id.json

  • GET /api/orders/:order_id.json will return the specified order.
Example:

$ curl -s \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u APP_API_KEY:APP_API_PASSWORD \
-X GET \
http://shop_subdomain.versacommerce.de/api/orders/:order_id.json

Status: 200 OK

{
  "order": {
    "bank_account_bank_code": null,
    "bank_account_bank_name": null,
    "bank_account_name": null,
    "bank_account_number": null,
    "checkout_locale": "de",
    "code": "196-083-565",
    "coupon_code": null,
    "coupon_value": "0.0",
    "created_at": "2013-03-19T12 =>39 =>51+01 =>00",
    "currency": "€",
    "customer_email": "support@versacommerce.de",
    "customer_id": 1000,
    "discount_total": "0.0",
    "external_invoicing_id": null,
    "id": 100,
    "item_total": "8.49",
    "items_count": 1,
    "items_status": "undelivered",
    "note": "Lorem ipsum dolor sit amet...",
    "payment_cost": "2.5",
    "payment_status": "not_paid",
    "payment_tax_rate": 19,
    "payment_type": "cod",
    "payments_count": 0,
    "prices_include_tax": true,
    "reduced_tax_amount": "0.0",
    "reduced_tax_rate": 7,
    "reduced_tax_total": "0.0",
    "referrer": "/",
    "shipments_count": 0,
    "shipping_cost": "4.95",
    "shop_id": 953,
    "source": null,
    "standard_tax_amount": "2.55",
    "standard_tax_rate": 19,
    "standard_tax_total": "15.94",
    "status": "canceled",
    "subtotal": "15.94",
    "total": "15.94",
    "weight_total": 0,
    "shipping_address": {
      "category": "shipping",
      "city": "Welver",
      "company": "VersaCommerce",
      "country": "DE",
      "customer_id": 1000,
      "email": "support@versacommerce.de",
      "extension": "",
      "firstname": "Eduard",
      "id": 10000,
      "lastname": "Siebert",
      "locked": true,
      "option_01": "",
      "option_02": "",
      "option_03": "",
      "order_id": 100,
      "phone": "+49 511 1659 800",
      "state": "unbekannt",
      "street": "Zwischen Den Hölzern",
      "streetnumber": "1a",
      "title": "Herr",
      "zipcode": "59514"
    },
    "billing_address": {
      "category": "billing",
      "city": "Welver",
      "company": "VersaCommerce",
      "country": "DE",
      "customer_id": 1000,
      "email": "support@versacommerce.de",
      "extension": "",
      "firstname": "Eduard",
      "id": 10001,
      "lastname": "Siebert",
      "locked": true,
      "option_01": "",
      "option_02": "",
      "option_03": "",
      "order_id": 100,
      "phone": "+49 511 1659 800",
      "state": "unbekannt",
      "street": "Zwischen Den Hölzern",
      "streetnumber": "1a",
      "title": "Herr",
      "zipcode": "59514"
    },
    "customer": {
      "accepts_newsletter": false,
      "account_confirmation_sent": false,
      "active": true,
      "birthday": null,
      "created_on": "2012-11-09",
      "email": "support@versacommerce.de",
      "id": 1000,
      "note": null,
      "option_01": "",
      "option_02": "",
      "option_03": "",
      "option_04": "",
      "registered": true,
      "shop_id": 953,
      "updated_on": "2012-11-09"
    }
  }
}


Get Orders Count

GET /api/orders/count.json

  • GET /api/orders/count.json will return the orders count.
Example:

$ curl -s \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u APP_API_KEY:APP_API_PASSWORD \
-X GET \
http://shop_subdomain.versacommerce.de/api/orders/count.json

Status: 200 OK

{
  "count": 117
}


Filter Orders

GET /api/orders.json?filter_name1=filter_value1&filter_name2=filter_value2

  • GET /api/orders.json?filter_name_1=filter_value_1&filter_name_2=filter_value_2 will return a filtered list of orders. See the Get Orders endpoint for more info about the output.

Available Filters and Options

Filter-/Optionname
Description
Type
Parameter
limit
The amount of results, defaults to 150, maximum are 250
Integer
limit=10
offset
The amount of results to omit
Integer
offset=10
include
Include one or more order associations (format: items, shipments, payments, histories, …)
String
include=items
coupon_value
Filter by coupon_value
String
coupon_value=10.0
code
Filter by order number (Order number is unique, so the result is always a single order)
String
code=012-345-678
items_status
Filter by items_status
String
items_status=undelivered
status
Filter by order status
String
status=open
payment_status
Filter by payment_status
String
payment_status=not_paid
payment_type
Filter by payment_type
String
payment_type=cod
shipping_type
Filter by shipping_type
String
shipping_type= shipping_type
external_invoicing_id
Filter by external_invoicing_id
String
external_invoicing_id=q1
note
Filter by note
String
note=content
subtotal
Filter by subtotal
BigDecimal
subtotal=100.0
total
Filter by total
BigDecimal
total=100.0
id_min
Filter orders by the minimum id
Integer
id_min=10
id_max
Filter orders by the maximum id
Integer
id_max=10
total_min
Filter orders by the minimum total
BigDecimal
total_min=100.0
total_max
Filter orders by the maximum total
BigDecimal
total_max=100.0
coupon_value_min
Filter orders by the minimum coupon value
BigDecimal
coupon_value_min=10.0
coupon_value_max
Filter orders by the maximum coupon value
BigDecimal
coupon_value_max=10.0
created_at_min
Filter to show orders created after date
DateTime
created_at_min= 2019-12-31
created_at_max
Filter to show orders created before date
DateTime
created_at_max= 2019-12-31

  • GET /api/orders.json?include=items will return all orders and order items (nested). See the Get Orders endpoint for more info about the output.

Example:

$ curl -s \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u APP_API_KEY:APP_API_PASSWORD \
-X GET \
"http://shop_subdomain.versacommerce.de/api/orders.json?include=items"

Status: 200 OK

[
  {
    "order": {
      "code": "199-187-329",
      "id": 100,
      "items_count": 2,
      ...
      "items": [{
          "id": 1000,
          "order_id": 100,
          "product_id": 10000,
          "quantity": 5,
          ...
        },
        {
          "id": 1001,
          "order_id": 100,
          "product_id": 10001,
          "quantity": 1,
          ...
        }
      ],
      ...
    }
  }, {
    "order": {
      "code": "199-267-382",
      "id": 101,
      "items_count": 2,
      ...
      "items": [{
          "id": 1002,
          "order_id": 101,
          "product_id": 10002,
          "quantity": 2,
          ...
        },
        {
          "id": 1003,
          "order_id": 101,
          "product_id": 10003,
          "quantity": 7,
          ...
        },
        {
          "id": 1004,
          "order_id": 101,
          "product_id": 10004,
          "quantity": 1,
          ...
        }
      ],
      ...
    }
  },
  ...
]


Create Order

POST /api/orders.json

  • POST /api/orders.json will create a new Order from the parameters passed.


Example:

$ curl -s \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u APP_API_KEY:APP_API_PASSWORD \
-X POST \
-d \
'{
"order": {
"payment_type": "misc",
"payment_cost": 0.0,
"item_total": 0.0,
"total": 0.0,
"subtotal": 0.0,
"weight_total": 1.0,
"shipping_cost": 1.0,
"items": [{
"product_id": 1,
"quantity": 1,
}],
"billing_address": {
"firstname": "my firstname",
"lastname": "my lastname",
"street": "my street",
"streetnumber": 1,
"zipcode": 12345,
"city": "Hannover"},
"shipping_address": {
"firstname": "my firstname",
"lastname": "my lastname",
"street": "mystreet",
"streetnumber": 1,
"zipcode": 12345,
"city": "Hannover" }}}
' \
http://shop_subdomain.versacommerce.de/api/orders.json

Status: 201 Created

{
  "payment_type": "misc",
  "payment_cost": 0.0,
  "item_total": 0.0,
  "total": 0.0,
  "subtotal": 0.0,
  "weight_total": 1.0,
  "shipping_cost": 1.0,
  "items": [{
    "product_id": 1,
    "code": 1,
    "quantity": 1,
    "title": "my order",
    "price": 1,
    "status": "shipped",
    "weight": 1,
    "tax_rate": 1,
    "origin_id": 1
  }]
}

Possible Parameter for POST /api/orders.json

# Required attributes / Benötigte Attribute:

order[payment_type]         = 'misc' # Zahlungsart (über die API i.d.R. 'misc') (Pflicht)
order[payment_cost]         = 0.00   # Kosten für die Zahlungsart (Pflicht, kann aber 0.0 sein)
order[item_total]           = 0.00   # Summe vom Warenwert
order[total]                = 0.00   # Gesamtpreis
order[subtotal]             = 0.00   # Zwischensumme
order[weight_total]         = 0.00   # Summe des Gewichts
order[shipping_cost]        = 0.00   # Versandkosten

# An Order must at least contain one item with the following attributes:

order[items][][product_id]    = 12345 # Position: VersaCommerce Product ID
order[items][][quantity]      = 3     # Position: Anzahl

# An Order must contain a billing address with the following attributes:

order[shipping_address][firstname]    = '...' # Lieferadresse: Vorname
order[shipping_address][lastname]     = '...' # Lieferadresse: Nachname
order[shipping_address][street]       = '...' # Lieferadresse: Straße
order[shipping_address][streetnumber] = '...' # Lieferadresse: Hausnummer
order[shipping_address][zipcode]      = '...' # Lieferadresse: PLZ
order[shipping_address][city]         = '...' # Lieferadresse: Stadt

order[billing_address][firstname]    = '...' # Rechnungsadresse: Vorname
order[billing_address][lastname]     = '...' # Rechnungsadresse: Nachname
order[billing_address][street]       = '...' # Rechnungsadresse: Straße
order[billing_address][streetnumber] = '...' # Rechnungsadresse: Hausnummer
order[billing_address][zipcode]      = '...' # Rechnungsadresse: PLZ
order[billing_address][city]         = '...' # Rechnungsadresse: Stadt



# Optional Attributes / Ab hier sind alle Angaben optional:

order[coupon_code]          = '...'  # Coupon- / Gutschein-Code
order[coupon_value]         = 0.0    # Wert des Coupons
order[standard_tax_total]   = 15.99  # Summer der Steuern (Haupsteuersatz) (Warenwert, Versandkostensplit, etc.)
order[standard_tax_amount]  = 12.99  # Summer der Steuern (Haupsteuersatz) (Warenwert)
order[reduced_tax_total]    = 15.99  # Summer der Steuern (reduzierter Steuersazu) (Warenwert, Versandkostensplit, etc.)
order[reduced_tax_amount]   = 12.99  # Summer der Steuern (reduzierter Steuersazu) (Warenwert)
order[note]                 = '...'  # Notiz (z.B. aus dem Warenkorb)
order[source]               = '...'  # Affiliate
order[referrer]             = '...'  #
order[origin_name]          = '...'  # Name der Bestellquelle (z.B. amazon)
order[origin_id]            = '...'  # ID der Bestellquelle ('1234-123435-124243')
order[customer_id]          = 123    # VersaCommerce Kunden ID
order[created_at]           = '2016-09-09 12:32' # Bestelldatum

# Optionale Attribute aus der Bestellquelle:

order[origin_custom_fields][my_custom_attrib_1] = 'Lorem ipsum ...'
order[origin_custom_fields][my_custom_attrib_2] = 'dolor sit ...'
...

order[items][][code]          = '...' # Position: Artikelnummer / EAN
order[items][][subtitle]      = '...' # Position: Untertitel
order[items][][title]         = '...' # Position: Titel
order[items][][weight]        = 0.0   # Position: Gewicht in kg
order[items][][price]         = 10.99 # Position: Einzelpreis
order[items][][status]        = '...' # Position: Status ('backorder', 'canceled', 'delivered', 'packing', 'partial_delivery', 'partial_packing', 'returned', 'shipped', 'undelivered')
order[items][][length]        = 0.0   # Position: Länge in cm
order[items][][width]         = 0.0   # Position: Breite in cm
order[items][][height]        = 0.0   # Position: Höhe in cm
order[items][][extra_price]   = 0.0   # Position: Extra Preis für diese Position
order[items][][category]      = '...' # Position: Kategorie
order[items][][tax_rate]      = 19.0  # Position: Steuersatz
order[items][][tax_category]  = '...' # Position: Steuertyp ('standard' / 'reduced')
order[items][][discount_type] = '...' # Position: Rabatt-Typ ('money' / 'percent')
order[items][][discount]      = 0.0   # Position: Rabatt-Wert (Wert oder Prozentwert)
order[items][][vendor]        = '...' # Position: Hersteller
order[items][][options]       = {}    # Position: Optinale Attribute
order[items][][origin_id]     = '...' # Position: Original ID (Quellsystem)
order[items][][asin]          = '...' # Position: Amazon Standard Identification Number

# Zahlungen als Array:

order[payments][][category] = 'misc'         # Zahlungen: Über die API i.d.R. 'misc'
order[payments][][amount]   = 123.45         # Zahlungen: Betrag
order[payments][][currency] = 'EUR'          # Zahlungen: Währung (ISO 4217)
order[payments][][comment]  = 'Freitext ...' # Zahlungen: Sofortüberweisung.de
order[payments][][trans_id] = ''             # Zahlungen: Transaktions ID (wenn vorhanden)

# Bestellhistories als Array:

order[histories][] = 'Notiz 1'
order[histories][] = 'Notiz 2'

# Die Adress- und Kundendaten sind alle optional (#POS) sollten aber natürlich befüllt werden.

order[customer][email]              = '...'        # Kundendaten: E-Mail Adresse des Kunden
order[customer][birthday]           = '1970-01-01' # Kundendaten: Geburtsdatum
order[customer][active]             = true         # Kundendaten: Aktiv (true/false)
order[customer][accepts_newsletter] = true         # Kundendaten: Newsletterzustimmung (true/false)
order[customer][wants_account]      = true         # Kundendaten: Kundenkonto erstellen (true/false)
order[customer][note]               = '...'        # Kundendaten: Notiz
order[customer][option_01]          = '...'        # Kundendaten: Feld für weitere Angaben
order[customer][option_02]          = '...'        # Kundendaten: Feld für weitere Angaben
order[customer][option_03]          = '...'        # Kundendaten: Feld für weitere Angaben
order[customer][option_04]          = '...'        # Kundendaten: Feld für weitere Angaben

order[billing_address][title]        = '...' # Rechnungsadresse: Titel
order[billing_address][extension]    = '...' # Rechnungsadresse: Adresszusatz
order[billing_address][state]        = '...' # Rechnungsadresse: Bundesland oder Staat (US)
order[billing_address][country]      = '...' # Rechnungsadresse: Land (ISO 3166-1 alpha-2)
order[billing_address][company]      = '...' # Rechnungsadresse: Firma
order[billing_address][phone]        = '...' # Rechnungsadresse: Telefonnummer
order[billing_address][option_01]    = '...' # Rechnungsadresse: Feld für weitere Angaben
order[billing_address][option_02]    = '...' # Rechnungsadresse: Feld für weitere Angaben
order[billing_address][option_03]    = '...' # Rechnungsadresse: Feld für weitere Angaben

order[shipping_address][title]        = '...' # Lieferadresse: Titel
order[shipping_address][extension]    = '...' # Lieferadresse: Adresszusatz
order[shipping_address][state]        = '...' # Lieferadresse: Bundesland oder Staat (US)
order[shipping_address][country]      = '...' # Lieferadresse: Land (ISO 3166-1 alpha-2)
order[shipping_address][company]      = '...' # Lieferadresse: Firma
order[shipping_address][phone]        = '...' # Lieferadresse: Telefonnummer
order[shipping_address][option_01]    = '...' # Lieferadresse: Feld für weitere Angaben
order[shipping_address][option_02]    = '...' # Lieferadresse: Feld für weitere Angaben
order[shipping_address][option_03]    = '...' # Lieferadresse: Feld für weitere Angaben



order[new_status]         = '...' # Bestellstatus ('canceled', 'closed', 'in_progress', 'open', 'open_or_in_progress', 'returned')
order[new_payment_status] = '...' # Bezahlstatus ('capture_error', 'captured', 'declined', 'not_paid', 'overpaid', 'paid', 'partial_payment', 'reserved')
order[items_status]       = '...' # Itemsstatus ('backorder', 'canceled', 'delivered', 'packing', 'partial_delivery', 'partial_packing', 'returned', 'shipped', 'undelivered')


    • Related Articles

    • Order

      order.bank_account_bank_bic BIC: {{ order.bank_account_bank_bic }} BIC: 123-456-789 order.bank_account_bank_code BLZ: {{ order.bank_account_bank_code }} BLZ: 123456789 order.bank_account_bank_iban IBAN: {{ order.bank_account_bank_iban }} IBAN: ...
    • Shipment Resource

      Attention Shipment resources are read-only by default. Please contact us at support@versacommerce.de if you need write permissions. Get Shipments GET /api/shipments.json GET /api/shipments.json will return the first 150 (default limit) items. You can ...
    • Payment Resource

      Payment resources are read-only by default. Please contact us if you need write permissions. Payment Categories Payment category English German cod Cash on delivery Bezahlung bei Lieferung custom Custom Eigene Zahlart bank_deposit Bank deposit ...
    • Item Resource

      Those resources are read-only by default. Please contact us if you need write permissions. Get Items GET /api/items.json GET /api/items.json will return the first 150 (default limit) items. You can increase the limit to a maximum of 250 items. GET ...
    • Metafield Resource

      Metafield Resource Get Metafields Get Metafield Create Metafield Update Metafield Delete Metafield Get Metafield Count Filter Metafields Get Metfields GET /api/metafields.json GET /api/metafields.json will return all Metafields. See the Filter ...