General notes

Introduction

Create and modify orders. Get status callbacks.

Endpoints

Sandbox: https://sandbox.api.mypromo.com/
Live: https://api.mypromo.com/

Registration

Sandbox: https://sandbox.connect.mypromo.com/
Live: https://connect.mypromo.com/

Behavior Sandbox vs. Live

Orders sent to Sandbox will not be forwarded to production. Instead we simulate a production and sent callbacks to your webhook and/or emails with partially random values for testing within short intervalls.

All orders sent to the live api will be pushed to production after the delay you set in your client configuration.

Authentication

Request an oAuth 2.0 token with your client credentials to access private routes.

Error Codes

200 | Successful
201 | Created
202 | Changed or deleted
204 | No content
400 | Bad request
401 | Unauthorized
403 | Forbidden
404 | Not found
405 | Method not allowed
406 | Not acceptable
410 | Gone
422 | Unprocessable entity
429 | Too many requests
500 | Internal server error
503 | Service unavailable (e.g. Maintenance Mode)

Rate limit

500 per Minute

Event notifications

A webhook can be defined in your client setup.

All events will be sent as a POST with a complete JSON repesentation of an order and details.
See response example of ‘Get order by id’.

You can optionally specify a custom header or basic auth in your client configuration.

SDK

A PHP SDK is available as a composer package. See details on github.

Postman Collection

Get our Postman Collection for using with Postman. Environments: Live, Sandbox. Globals: Globals

API detail

Authentication & General

Getting startet…

Get oAuth token

This API uses oAuth 2.0 authentication.
In order to get your token use the credentials of the client you created after you signed up with us.

The token livetime is 1 month.
Invalid tokens result in error code 401 - Unauthorized.
No rights result in 403 - Forbidden.

Scopes: * | MERCHANT | FULFILLER

HTTP Request
POST {{ENDPOINT}}oauth/token
Headers
Content-Type
application/json
Accept
application/json
PayLoad
{
    "grant_type": "client_credentials",
    "client_id": "{{CLIENTID}}",
    "client_secret": "{{CLIENTSECRET}}",
    "scope": "*"
}
Example request
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -d '{
    "grant_type": "client_credentials",
    "client_id": "{{CLIENTID}}",
    "client_secret": "{{CLIENTSECRET}}",
    "scope": "*"
}' "{{ENDPOINT}}oauth/token"
POST %7B%7BENDPOINT%7D%7Doauth/token HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json

{
    "grant_type": "client_credentials",
    "client_id": "{{CLIENTID}}",
    "client_secret": "{{CLIENTSECRET}}",
    "scope": "*"
}
Example response
Status 401 Unauthorized
{
    "error": "invalid_client",
    "error_description": "Client authentication failed",
    "message": "Client authentication failed"
}
Status 200 OK
{
    "token_type": "Bearer",
    "expires_in": 31622400,
    "access_token": "YOURACCESSTOKEN"
}

Status of the API

If you like to monitor our service, please use this route.

HTTP Request
GET {{ENDPOINT}}v1/status
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/status"
GET %7B%7BENDPOINT%7D%7Dv1/status HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 503 Service Unavailable
{
    "message": "We are in maintenance mode. Please try again later."
}
Status 200 OK
{
    "message": "OK"
}

Editor

Create design user

Creates a new reusable user for the designer.

All uploaded media are assigned to this user. So those media will be available with the next design and can be reused.

HTTP Request
POST {{ENDPOINT}}v1/editor_user
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/editor_user"
POST %7B%7BENDPOINT%7D%7Dv1/editor_user HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 201 Created
{
    "editor_user_hash": "7B0BEqcuJCvpMCij1uooGQzdE1zXNZ4PdZcTgeJITGOcFWEluBU2rBhoaaCQOzVr"
}

Create design

Creates a new designer draft.
Note: To use this route please create a design user first!

Specify a returnURL to redirect to after the design process has finished in the payload.

For intent use one of the possible values you can retrieve from the products route.
If not given default is customize if available, then upload if available otherwise bad request.

You can use placeholders in the return or cancel urls that will be replaced with e.g. the design value.

Available Placeholders:

  • DESIGNID
  • USERHASH
  • INTENT

Returns

  • unique identifier (for ordering after your checkout process)

  • intent that has been given or default if none has given

  • given editor user (to reuse past uploads / user based media database)

  • URL to start the editor

    • autogen of jwt token + redirect to editor
    • can be used for opening editor in new windows

  • URL to your optionally configured CNAME in your client setup pointing to our editor

    • the jwt token is session based
    • GET /design generates a new one
    • can be used in iframes e.g. nested in modals, lightboxes etc.
    • this is more peachy and the more secure version to implement into your shop

  • URL to get a preview of the design

Attention!

The response contains the given SKU as long as the user did not change the variant in the editor. If user changed e.g. the color in the editor our api will automatically switch to the correct SKU. So please keep in mind to compare any response (or latest when submitting the design) with your initial given SKU and update afterwards in your system. In case it’s a product with stock details you should check those as well.

HTTP Request
POST {{ENDPOINT}}v1/designs
Headers
Content-Type
application/json
Accept
application/json
PayLoad
{
    "sku": "MP-F1-C0000003",
    "intent": "upload",
    "editor_user_hash": "{{EDITORUSERHASH}}",
    "return_url": "https://yourshop.com/basket/TPD123LD02LAXALOP/{DESIGNID}/add/{INTENT}/{USERHASH}/{INTENT}/{DESIGNID}",
    "cancel_url": "https://yourshop.com/product/TPD123LD02LAXALOP/design/{DESIGNID}/user/{USERHASH}"
}
Example request
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -d '{
    "sku": "MP-F1-C0000003",
    "intent": "upload",
    "editor_user_hash": "{{EDITORUSERHASH}}",
    "return_url": "https://yourshop.com/basket/TPD123LD02LAXALOP/{DESIGNID}/add/{INTENT}/{USERHASH}/{INTENT}/{DESIGNID}",
    "cancel_url": "https://yourshop.com/product/TPD123LD02LAXALOP/design/{DESIGNID}/user/{USERHASH}"
}' "{{ENDPOINT}}v1/designs"
POST %7B%7BENDPOINT%7D%7Dv1/designs HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json

{
    "sku": "MP-F1-C0000003",
    "intent": "upload",
    "editor_user_hash": "{{EDITORUSERHASH}}",
    "return_url": "https://yourshop.com/basket/TPD123LD02LAXALOP/{DESIGNID}/add/{INTENT}/{USERHASH}/{INTENT}/{DESIGNID}",
    "cancel_url": "https://yourshop.com/product/TPD123LD02LAXALOP/design/{DESIGNID}/user/{USERHASH}"
}
Example response
Status 201 Created
{
    "id": 9,
    "sku": "MP-F1-C0000003",
    "intent": "upload",
    "editor_user_hash": "7B0BEqcuJCvpMCij1uooGQzdE1zXNZ4PdZcTgeJITGOcFWEluBU2rBhoaaCQOzVr",
    "editor_start_url": "https://connect.mypromo.com/editor/180/show/CvOOfxW",
    "editor_start_url_cname": "https://designer.yourserver.com/auth?jwt=eyJqdGkiOiJZWHI4anZmMW5PTmtrcE8iLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjbGllbnQiOiJtOUlwNjlhQyIsInVzZXIiOiJvNWhIZ0V2QyIsImlhdCI6MTU5NDAzNjE5MCwicmVkaXJlY3QiOiJodHRwczpcL1wvZWRpdG9yLm15cHJvbW8uY29tXC9lZGl0b3JcL3loemgwNmFiem05bXJoMGFqYXNuanE1MWt4ZHpjaHZmXC9lZGl0In0.byIkJWRJnbX7MZavKD4d4YsIn55BGjqNCSzLT8b3tk0",
    "preview_url": "https://connect.mypromo.com/aOdkik",
    "return_url": "https://yourshop.com/basket/TPD123LD02LAXALOP/add/9",
    "cancel_url": "https://yourshop.com/product/TPD123LD02LAXALOP",
    "status": "PENDING"
}
Status 201 Created
{
    "id": 9,
    "sku": "MP-F1-C0000003",
    "intent": "upload",
    "editor_user_hash": "7B0BEqcuJCvpMCij1uooGQzdE1zXNZ4PdZcTgeJITGOcFWEluBU2rBhoaaCQOzVr",
    "editor_start_url": "https://connect.mypromo.com/editor/180/show/CvOOfxW",
    "editor_start_url_cname": null,
    "preview_url": "https://connect.mypromo.com/aOdkik",
    "return_url": "https://yourshop.com/basket/TPD123LD02LAXALOP/add/9",
    "cancel_url": "https://yourshop.com/product/TPD123LD02LAXALOP",
    "status": "PENDING"
}
Status 422 Unprocessable Entity
{
    "message": "The given data was invalid.",
    "errors": {
        "sku": [
            "The selected sku is invalid."
        ]
    }
}

Get design

Get representation of a created design with preview of the current state of edit or the last before design was submitted.

HTTP Request
GET {{ENDPOINT}}v1/designs/{{DESIGNID}}
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/designs/{{DESIGNID}}"
GET %7B%7BENDPOINT%7D%7Dv1/designs/%7B%7BDESIGNID%7D%7D HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 200 OK
{
    "id": 9,
    "sku": "MP-F1-C0000003",
    "intent": "upload",
    "editor_user_hash": "hfgtu684jd62msmc",
    "editor_start_url": "https://connect.mypromo.com/editor/180/show/CvOOfxW",
    "editor_start_url_cname": null,
    "preview_url": "https://connect.mypromo.com/aOdkik",
    "status": "PENDING"
}

Get preview

Get binary stream of the current state of edit or the last before design was submitted.

HTTP Request
GET {{ENDPOINT}}v1/designs/{{DESIGNID}}/preview
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/designs/{{DESIGNID}}/preview"
GET %7B%7BENDPOINT%7D%7Dv1/designs/%7B%7BDESIGNID%7D%7D/preview HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json

Submit design

This confirms a design and editing / start of editor is not possible anymore.

The preview URL will stay active and returns the latest one.

HTTP Request
POST {{ENDPOINT}}v1/designs/{{DESIGNID}}/submit
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/designs/{{DESIGNID}}/submit"
POST %7B%7BENDPOINT%7D%7Dv1/designs/%7B%7BDESIGNID%7D%7D/submit HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 200 OK
{
    "id": 9,
    "sku": "MP-F1-C0000003",
    "intent": "upload",
    "editor_user_hash": "7B0BEqcuJCvpMCij1uooGQzdE1zXNZ4PdZcTgeJITGOcFWEluBU2rBhoaaCQOzVr",
    "editor_start_url": "https://connect.mypromo.com/editor/180/show/CvOOfxW",
    "editor_start_url_cname": null,
    "preview_url": "https://connect.mypromo.com/aOdkik",
    "return_url": "https://yourshop.com/basket/TPD123LD02LAXALOP/add/9",
    "cancel_url": "https://yourshop.com/product/TPD123LD02LAXALOP",
    "status": "SUBMITTED"
}

Create an order

Create your order in 3 steps.

  • Create an order
  • Add max. 50 items / Add max. 1 item if you provide shipping documents
  • Submit the order

Create order

Create an order by providing basic things like the recipient address, customs relevant data, some references etc.

With “callback” you can overwrite the settings of your client setup for each order (method: GET, url: webhook or api endpoint, auth: basic|header|oauth1|oauth2).

Available auth objects for callbacks:

  • auth: basic => username + password
  • auth: header
  • auth: oauth1 => username, password, auth_url
  • auth: oauth2 => username, password, auth_url, grant_type (password_grant), scope
  • auth: oauth2 => client_id, client_secret, auth_url, grant_type (client_credentials),scope

Note: Submission of “order.files” or “order.generic_label” is optional and just available on request.
Fulfillers are advised to download labels on day of dispatch.

Explanation:

  • Delivery slips have to be A4 and will be printed and added to packages. GET call. Expected header: application/pdf
  • Labels will be printed and used as shipping label. GET call. Expected header: application/pdf
  • Generic labels can be links or API Routes at your side. GET call. Expected response is a JSON containing a link to a pdf ressource (application/pdf) and one of our carrier codes (see GET carriers) and tracking code in order to have smooth processes.

Expected response for generic labels:

{
“url”: “https://yourserver.com/label/reference",
“carrier”: “dhl”,
“tracking_code”: “1234567890”,
}

Address validation

  • reference: 2-50, optional
  • firstname: 0-30, optional
  • lastname: 0-30, mandatory if company empty
  • company: 0-30, mandatory if lastname empty
  • street: 0-30, optional
  • care_of: 0-30, optional
  • zip: 3-10, mandatory
  • city: 2-30, mandatory
  • district: 0-30, optional
  • phone: 0-30, optional
  • fax: 0-30, optional
  • mobile: 0-30, optional
  • vat_id: 0-30, optional
  • email: 0-255, valid email, optional
  • country_code: iso2 or iso3, required
  • commercial_registry_entry: 2-50, optional

Note: If no address data or address_id or address_key is provided for shipper or export in the payload we will take the assigned address data from your client if valid! The recipient has always to be given in the payload.

Testing / Sandbox:

  • fake_preflight = bool
  • fake_shipment = bool

In our sandbox environment preflight is switched off and a fake dispatch is switched on by default. That enables clients of type merchant to onboard theirself easier (receive automatically callbacks with fake shipments or use any test pdf files in the first step of integration). If you do integration for a client of type fulfiller (e.g. creating a dummy client of type merchant, ordering products of your own fulfiller client) and want to avoid e.g. shipments will be faked and use the add shipment route, just set this option to false. Both options are available in our sandbox system only. Please ensure not to use those in the live environment.

HTTP Request
POST {{ENDPOINT}}v1/orders
Headers
Content-Type
application/json
Accept
application/json
PayLoad
{
    "reference": "{{$timestamp}}",
    "reference2": null,
    "complaint": false,
    "express_production": false,
    "express_shipping": false,
    "fake_preflight": false,
    "fake_shipment": false,
    "callback": {
        "url": "https://downloads.test.mypromo.com:10433/callback.php",
        "auth": {
            "oauth2": {
                "client_id": "id",
                "client_secret": "secret",
                "auth_url": "https://myshop.com/api/auth",
                "grant_type": "client_credentials"
            }
        }
    },
    "generic_label": {
        "url": "https://downloads.test.mypromo.com/genericLabel/{{$guid}}",
        "auth": {
            "oauth2": {
                "client_id": "id",
                "client_secret": "secret",
                "auth_url": "https://myshop.com/api/auth",
                "grant_type": "client_credentials"
            }
        }
    },
    "custom_properties": [
        {
            "key": "property1",
            "value": "value1"
        },
        {
            "key": "property2",
            "value": "value2"
        },
        {
            "key": "property3",
            "value": "value3"
        }
    ],
    "shipper": {
        "address_id": null,
        "address_key": null,
        "reference": "{{$guid}}",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+4991234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": "",
        "commercial_register_entry": "Test123"
    },
    "recipient": {
        "reference": "{{$guid}}",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+491234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": null,
        "commercial_register_entry": "Test321"
    },
    "export": {
        "address_id": null,
        "address_key": null,
        "reference": "{{$guid}}",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+491234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": null,
        "iban": "DE89370400440532013000",
        "bic_or_swift": "WELADED1SIE",
        "account_holder": "Sam Sample",
        "eori_number": null,
        "commercial_register_entry": "Test321444"
    },
    "files": [
        {
            "url": "https://downloads.test.mypromo.com:8080/lfs.pdf",
            "type": "deliverySlip",
            "auth": {
                "basic": {
                    "username": "user",
                    "password": "pass"
                }
            }
        },
        {
            "url": "https://downloads.test.mypromo.com/label2.pdf",
            "type": "label",
            "carrier": "ups",
            "tracking_code": "1Z123891378124",
            "auth": {
                "header": "Bearer: 1231313123"
            }
        },
        {
            "url": "sftp://downloads.test.mypromo.com/upload/label2.pdf",
            "type": "label",
            "carrier": "ups",
            "tracking_code": "1Z123891378125",
            "auth": {
                "basic": {
                    "username": "user",
                    "password": "pass"
                }
            }
        }
    ]
}
Example request
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -d '{
    "reference": "{{$timestamp}}",
    "reference2": null,
    "complaint": false,
    "express_production": false,
    "express_shipping": false,
    "fake_preflight": false,
    "fake_shipment": false,
    "callback": {
        "url": "https://downloads.test.mypromo.com:10433/callback.php",
        "auth": {
            "oauth2": {
                "client_id": "id",
                "client_secret": "secret",
                "auth_url": "https://myshop.com/api/auth",
                "grant_type": "client_credentials"
            }
        }
    },
    "generic_label": {
        "url": "https://downloads.test.mypromo.com/genericLabel/{{$guid}}",
        "auth": {
            "oauth2": {
                "client_id": "id",
                "client_secret": "secret",
                "auth_url": "https://myshop.com/api/auth",
                "grant_type": "client_credentials"
            }
        }
    },
    "custom_properties": [
        {
            "key": "property1",
            "value": "value1"
        },
        {
            "key": "property2",
            "value": "value2"
        },
        {
            "key": "property3",
            "value": "value3"
        }
    ],
    "shipper": {
        "address_id": null,
        "address_key": null,
        "reference": "{{$guid}}",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+4991234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": "",
        "commercial_register_entry": "Test123"
    },
    "recipient": {
        "reference": "{{$guid}}",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+491234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": null,
        "commercial_register_entry": "Test321"
    },
    "export": {
        "address_id": null,
        "address_key": null,
        "reference": "{{$guid}}",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+491234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": null,
        "iban": "DE89370400440532013000",
        "bic_or_swift": "WELADED1SIE",
        "account_holder": "Sam Sample",
        "eori_number": null,
        "commercial_register_entry": "Test321444"
    },
    "files": [
        {
            "url": "https://downloads.test.mypromo.com:8080/lfs.pdf",
            "type": "deliverySlip",
            "auth": {
                "basic": {
                    "username": "user",
                    "password": "pass"
                }
            }
        },
        {
            "url": "https://downloads.test.mypromo.com/label2.pdf",
            "type": "label",
            "carrier": "ups",
            "tracking_code": "1Z123891378124",
            "auth": {
                "header": "Bearer: 1231313123"
            }
        },
        {
            "url": "sftp://downloads.test.mypromo.com/upload/label2.pdf",
            "type": "label",
            "carrier": "ups",
            "tracking_code": "1Z123891378125",
            "auth": {
                "basic": {
                    "username": "user",
                    "password": "pass"
                }
            }
        }
    ]
}' "{{ENDPOINT}}v1/orders"
POST %7B%7BENDPOINT%7D%7Dv1/orders HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json

{
    "reference": "{{$timestamp}}",
    "reference2": null,
    "complaint": false,
    "express_production": false,
    "express_shipping": false,
    "fake_preflight": false,
    "fake_shipment": false,
    "callback": {
        "url": "https://downloads.test.mypromo.com:10433/callback.php",
        "auth": {
            "oauth2": {
                "client_id": "id",
                "client_secret": "secret",
                "auth_url": "https://myshop.com/api/auth",
                "grant_type": "client_credentials"
            }
        }
    },
    "generic_label": {
        "url": "https://downloads.test.mypromo.com/genericLabel/{{$guid}}",
        "auth": {
            "oauth2": {
                "client_id": "id",
                "client_secret": "secret",
                "auth_url": "https://myshop.com/api/auth",
                "grant_type": "client_credentials"
            }
        }
    },
    "custom_properties": [
        {
            "key": "property1",
            "value": "value1"
        },
        {
            "key": "property2",
            "value": "value2"
        },
        {
            "key": "property3",
            "value": "value3"
        }
    ],
    "shipper": {
        "address_id": null,
        "address_key": null,
        "reference": "{{$guid}}",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+4991234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": "",
        "commercial_register_entry": "Test123"
    },
    "recipient": {
        "reference": "{{$guid}}",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+491234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": null,
        "commercial_register_entry": "Test321"
    },
    "export": {
        "address_id": null,
        "address_key": null,
        "reference": "{{$guid}}",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+491234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": null,
        "iban": "DE89370400440532013000",
        "bic_or_swift": "WELADED1SIE",
        "account_holder": "Sam Sample",
        "eori_number": null,
        "commercial_register_entry": "Test321444"
    },
    "files": [
        {
            "url": "https://downloads.test.mypromo.com:8080/lfs.pdf",
            "type": "deliverySlip",
            "auth": {
                "basic": {
                    "username": "user",
                    "password": "pass"
                }
            }
        },
        {
            "url": "https://downloads.test.mypromo.com/label2.pdf",
            "type": "label",
            "carrier": "ups",
            "tracking_code": "1Z123891378124",
            "auth": {
                "header": "Bearer: 1231313123"
            }
        },
        {
            "url": "sftp://downloads.test.mypromo.com/upload/label2.pdf",
            "type": "label",
            "carrier": "ups",
            "tracking_code": "1Z123891378125",
            "auth": {
                "basic": {
                    "username": "user",
                    "password": "pass"
                }
            }
        }
    ]
}
Example response
Status 201 Created
{
    "id": 9,
    "reference": "order ref",
    "reference2": null,
    "complaint": false,
    "express_production": false,
    "express_shipping": false,
    "shipping_earliest": null,
    "shipping_latest": null,
    "shipping_late": false,
    "status": "PENDING",
    "comment": null,
    "callback": {
        "url": "https://downloads.test.mypromo.com/callback.php",
        "authType": "oauth2"
    },
    "generic_label": {
        "url": "https://downloads.test.mypromo.com/genericLabel/{{$guid}}",
        "authType": "oauth2"
    },
    "custom_properties": [
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        }
    ],
    "shipper": {
        "id": 26,
        "reference": "ref",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+4991234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": null,
        "commercial_register_entry": "Test123"
    },
    "recipient": {
        "id": 28,
        "reference": "ref",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+491234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": null,
        "commercial_register_entry": "Test321"
    },
    "export": {
        "id": 27,
        "reference": "ref",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+491234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": null,
        "commercial_register_entry": "Test321444",
        "iban": null,
        "bic_or_swift": null,
        "account_holder": null,
        "eori_number": null
    },
    "items": [],
    "histories": [
        {
            "id": 80,
            "text": "New order created.",
            "created_at": "2019-08-13T22:39:56.000000Z"
        }
    ],
    "files": [
        {
            "id": 24,
            "url": "https://test-downloads.mypromo.com/lfs.pdf",
            "type": "deliverySlip",
            "carrier": null,
            "tracking_code": null,
            "status": "PENDING",
            "authType": "basic"
        },
        {
            "id": 25,
            "url": "sftp://test-downloads.mypromo.com/upload/label.pdf",
            "type": "label",
            "carrier": "UPS",
            "tracking_code": "1Z123891378123",
            "status": "PENDING",
            "authType": "header"
        }
    ],
    "shipments": [],
    "created_at": "2019-08-13T22:39:56.000000Z",
    "updated_at": "2019-08-13T22:39:56.000000Z"
}

Add item with print files

Add items and details where we can pick up your print files.

We offer two protocols:

  • https
  • sftp

sftp can be used after you provided valid credentials in your client setup.
For https you can optionally provide a custom header or basic auth in your client setup.
Auth type and credentials can be overwritten in your payload always.

Files are downloaded shortly after you submitted your order.
If we cant download the files of one or more items of an order we cancel the whole order.
You get notifed about canceled orders depending on your client setup by email or a callback to your webhook.
Details about the cancellation can be gathered from the history.

Available optional auth objects for files:

  • auth: basic => username + password (https + sftp)
  • auth: header (https)

If you submit order documents (labels or delivery slips) maximum 1 item per order is allowed!

HTTP Request
POST {{ENDPOINT}}v1/orders/{{ORDERID}}/items
Headers
Content-Type
application/json
Accept
application/json
PayLoad
{
    "reference": "{{$guid}}",
    "quantity": 100,
    "sku": "MP-F1-C0000003",
    "custom_properties": [
        {
            "key": "property-a",
            "value": "value-a"
        },
        {
            "key": "property-b",
            "value": "value-b"
        },
        {
            "key": "property-c",
            "value": "value-c"
        }
    ],
    "files": [
        {
            "url": "sftp://downloads.test.mypromo.com/upload/a4.pdf",
            "auth": {
                "basic": {
                    "username": "user",
                    "password": "pass"
                }
            }
        }
    ],
    "customs": {
        "description": "Printed matter, n.e.s.",
        "number": "49119900",
        "origin": "DE",
        "currency": "EUR",
        "amount": 10.5
    }
}
Example request
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -d '{
    "reference": "{{$guid}}",
    "quantity": 100,
    "sku": "MP-F1-C0000003",
    "custom_properties": [
        {
            "key": "property-a",
            "value": "value-a"
        },
        {
            "key": "property-b",
            "value": "value-b"
        },
        {
            "key": "property-c",
            "value": "value-c"
        }
    ],
    "files": [
        {
            "url": "sftp://downloads.test.mypromo.com/upload/a4.pdf",
            "auth": {
                "basic": {
                    "username": "user",
                    "password": "pass"
                }
            }
        }
    ],
    "customs": {
        "description": "Printed matter, n.e.s.",
        "number": "49119900",
        "origin": "DE",
        "currency": "EUR",
        "amount": 10.5
    }
}' "{{ENDPOINT}}v1/orders/{{ORDERID}}/items"
POST %7B%7BENDPOINT%7D%7Dv1/orders/%7B%7BORDERID%7D%7D/items HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json

{
    "reference": "{{$guid}}",
    "quantity": 100,
    "sku": "MP-F1-C0000003",
    "custom_properties": [
        {
            "key": "property-a",
            "value": "value-a"
        },
        {
            "key": "property-b",
            "value": "value-b"
        },
        {
            "key": "property-c",
            "value": "value-c"
        }
    ],
    "files": [
        {
            "url": "sftp://downloads.test.mypromo.com/upload/a4.pdf",
            "auth": {
                "basic": {
                    "username": "user",
                    "password": "pass"
                }
            }
        }
    ],
    "customs": {
        "description": "Printed matter, n.e.s.",
        "number": "49119900",
        "origin": "DE",
        "currency": "EUR",
        "amount": 10.5
    }
}
Example response
Status 201 Created
{
    "id": 8,
    "reference": "yourItemReference",
    "quantity": 5,
    "sku": "TPD123LD02LAXALOP",
    "type": "FILES",
    "shipping_earliest": null,
    "shipping_latest": null,
    "shipping_late": false,
    "status": "PENDING",
    "custom_properties": [
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        }
    ],
    "files": [
        {
            "id": 26,
            "url": "https://test-downloads.mypromo.com/a4.pdf",
            "status": "PENDING"
        }
    ],
    "designs": [],
    "customs": {
        "description": "Printed matter, n.e.s.",
        "number": "49119900",
        "origin": "DE",
        "currency": "EUR",
        "amount": 10.5
    }
}
Status 400 Bad Request
{
    "message": "You have no contract with this client. You can see your current contracts in the dashboard."
}

Add item with design

When using our editor add your designs to your order as follows.

HTTP Request
POST {{ENDPOINT}}v1/orders/{{ORDERID}}/items
Headers
Content-Type
application/json
Accept
application/json
PayLoad
{
    "reference": "{{$guid}}",
    "quantity": 50,
    "custom_properties": [
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        }
    ],
    "designs": [
        {
            "id": "{{DESIGNID}}"
        }
    ],
    "customs": {
        "description": "Printed matter, n.e.s.",
        "number": "49119900",
        "origin": "DE",
        "currency": "EUR",
        "amount": 10.5
    }
}
Example request
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -d '{
    "reference": "{{$guid}}",
    "quantity": 50,
    "custom_properties": [
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        }
    ],
    "designs": [
        {
            "id": "{{DESIGNID}}"
        }
    ],
    "customs": {
        "description": "Printed matter, n.e.s.",
        "number": "49119900",
        "origin": "DE",
        "currency": "EUR",
        "amount": 10.5
    }
}' "{{ENDPOINT}}v1/orders/{{ORDERID}}/items"
POST %7B%7BENDPOINT%7D%7Dv1/orders/%7B%7BORDERID%7D%7D/items HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json

{
    "reference": "{{$guid}}",
    "quantity": 50,
    "custom_properties": [
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        }
    ],
    "designs": [
        {
            "id": "{{DESIGNID}}"
        }
    ],
    "customs": {
        "description": "Printed matter, n.e.s.",
        "number": "49119900",
        "origin": "DE",
        "currency": "EUR",
        "amount": 10.5
    }
}
Example response
Status 201 Created
{
    "id": 116,
    "reference": "yourItemReference",
    "quantity": 5,
    "sku": "TESTPRODUCT123",
    "type": "DESIGNS",
    "shipping_earliest": null,
    "shipping_latest": null,
    "shipping_late": false,
    "status": "PENDING",
    "custom_properties": [
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        }
    ],
    "files": [],
    "designs": [
        {
            "id": 9,
            "editor_start_url": "https://editor.mypromo.com/editor/ficfclvsbarhw5ti7x3h9scojitu0bm6/edit",
            "preview_url": null,
            "status": "READY"
        }
    ],
    "customs": {
        "description": "Printed matter, n.e.s.",
        "number": "49119900",
        "origin": "DE",
        "currency": "EUR",
        "amount": 10.5
    }
}

Add item from stock

Use this request to add unpersonalized items such as stock items.

HTTP Request
POST {{ENDPOINT}}v1/orders/{{ORDERID}}/items
Headers
Content-Type
application/json
Accept
application/json
PayLoad
{
    "reference": "{{$guid}}",
    "quantity": 50,
    "sku": "TESTPRODUCT-stock",
    "custom_properties": [
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        }
    ],
    "customs": {
        "description": "Printed matter, n.e.s.",
        "number": "49119900",
        "origin": "DE",
        "currency": "EUR",
        "amount": 10.5
    }
}
Example request
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -d '{
    "reference": "{{$guid}}",
    "quantity": 50,
    "sku": "TESTPRODUCT-stock",
    "custom_properties": [
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        }
    ],
    "customs": {
        "description": "Printed matter, n.e.s.",
        "number": "49119900",
        "origin": "DE",
        "currency": "EUR",
        "amount": 10.5
    }
}' "{{ENDPOINT}}v1/orders/{{ORDERID}}/items"
POST %7B%7BENDPOINT%7D%7Dv1/orders/%7B%7BORDERID%7D%7D/items HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json

{
    "reference": "{{$guid}}",
    "quantity": 50,
    "sku": "TESTPRODUCT-stock",
    "custom_properties": [
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        }
    ],
    "customs": {
        "description": "Printed matter, n.e.s.",
        "number": "49119900",
        "origin": "DE",
        "currency": "EUR",
        "amount": 10.5
    }
}
Example response
Status 200 OK
{
    "id": 37,
    "reference": "yourItemReference",
    "quantity": 5,
    "sku": "TESTPRODUCT123",
    "type": "STOCK",
    "shipping_earliest": null,
    "shipping_latest": null,
    "shipping_late": null,
    "status": "PENDING",
    "custom_properties": [
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        }
    ],
    "files": [],
    "designs": [],
    "customs": {
        "description": "Printed matter, n.e.s.",
        "number": "49119900",
        "origin": "DE",
        "currency": "EUR",
        "amount": 10.5
    }
}

Add item from amazon custom

Add custom configurations from amazon orders.

Note: Not available yet.

HTTP Request
POST {{ENDPOINT}}v1/orders/{{ORDERID}}/items
Headers
Content-Type
application/json
Accept
application/json
PayLoad
{
    "reference": "{{$guid}}",
    "quantity": 50,
    "sku": "TESTPRODUCT-AMAZON",
    "custom_properties": [
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        }
    ],
    "amazon_custom": [
        {
            "url": "https://zme-caps.amazon.com/t/7fX4QLzhVVVp/fM8zDsXPd8bO5BCt_UeTW8ofrBByt_bQbuZ7VQDVFE0/8"
        }
    ],
    "customs": {
        "description": "Printed matter, n.e.s.",
        "number": "49119900",
        "origin": "DE",
        "currency": "EUR",
        "amount": 10.5
    }
}
Example request
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -d '{
    "reference": "{{$guid}}",
    "quantity": 50,
    "sku": "TESTPRODUCT-AMAZON",
    "custom_properties": [
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        }
    ],
    "amazon_custom": [
        {
            "url": "https://zme-caps.amazon.com/t/7fX4QLzhVVVp/fM8zDsXPd8bO5BCt_UeTW8ofrBByt_bQbuZ7VQDVFE0/8"
        }
    ],
    "customs": {
        "description": "Printed matter, n.e.s.",
        "number": "49119900",
        "origin": "DE",
        "currency": "EUR",
        "amount": 10.5
    }
}' "{{ENDPOINT}}v1/orders/{{ORDERID}}/items"
POST %7B%7BENDPOINT%7D%7Dv1/orders/%7B%7BORDERID%7D%7D/items HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json

{
    "reference": "{{$guid}}",
    "quantity": 50,
    "sku": "TESTPRODUCT-AMAZON",
    "custom_properties": [
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        }
    ],
    "amazon_custom": [
        {
            "url": "https://zme-caps.amazon.com/t/7fX4QLzhVVVp/fM8zDsXPd8bO5BCt_UeTW8ofrBByt_bQbuZ7VQDVFE0/8"
        }
    ],
    "customs": {
        "description": "Printed matter, n.e.s.",
        "number": "49119900",
        "origin": "DE",
        "currency": "EUR",
        "amount": 10.5
    }
}
Example response
Status 200 OK
{
    "id": 37,
    "reference": "yourItemReference",
    "quantity": 5,
    "sku": "TESTPRODUCT123",
    "type": "STOCK",
    "shipping_earliest": null,
    "shipping_latest": null,
    "shipping_late": null,
    "status": "PENDING",
    "custom_properties": [
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        }
    ],
    "files": [],
    "designs": [],
    "customs": {
        "description": "Printed matter, n.e.s.",
        "number": "49119900",
        "origin": "DE",
        "currency": "EUR",
        "amount": 10.5
    }
}

Submit order

Call this route to sent your order to production.

The status will switch from ‘new’ to ‘pending’, ‘preflight’ (we do some magic things like downloading your files and preparing other things) and afterwards to ‘ready’ or in case of an error to ‘canceled’.

After the delay you specified in your client setup we will sent your order to production.
If errors occour during this process we cancel the order and notify you depending on your client setup through mail or a callback with details in the history.

HTTP Request
POST {{ENDPOINT}}v1/orders/{{ORDERID}}/submit
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/orders/{{ORDERID}}/submit"
POST %7B%7BENDPOINT%7D%7Dv1/orders/%7B%7BORDERID%7D%7D/submit HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 200 OK
{
    "id": 9,
    "reference": "order ref",
    "reference2": null,
    "complaint": false,
    "express_production": false,
    "express_shipping": false,
    "shipping_earliest": null,
    "shipping_latest": null,
    "shipping_late": false,
    "status": "PROCESSING",
    "comment": null,
    "callback": {
        "url": "https://downloads.test.mypromo.com/callback.php"
    },
    "custom_properties": [
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        }
    ],
    "shipper": {
        "id": 26,
        "reference": "ref",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+4991234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": null,
        "commercial_register_entry": "Test123"
    },
    "recipient": {
        "id": 28,
        "reference": "ref",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+491234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": null,
        "commercial_register_entry": "Test321"
    },
    "export": {
        "id": 27,
        "reference": "ref",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+491234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": null,
        "commercial_register_entry": "Test321444",
        "iban": null,
        "bic_or_swift": null,
        "account_holder": null,
        "eori_number": null
    },
    "items": [
        {
            "id": 8,
            "reference": "yourItemReference",
            "quantity": 5,
            "sku": "TPD123LD02LAXALOP",
            "shipping_earliest": null,
            "shipping_latest": null,
            "shipping_late": false,
            "status": "PENDING",
            "custom_properties": [
                {
                    "key": "property",
                    "value": "value"
                },
                {
                    "key": "property",
                    "value": "value"
                },
                {
                    "key": "property",
                    "value": "value"
                }
            ],
            "files": [
                {
                    "id": 26,
                    "url": "https://test-downloads.mypromo.com/a4.pdf",
                    "type": "front",
                    "status": "PENDING"
                }
            ],
            "designs": [],
            "customs": {
                "description": "Printed matter, n.e.s.",
                "number": "49119900",
                "origin": "DE",
                "currency": "EUR",
                "amount": 10.5
            }
        }
    ],
    "histories": [
        {
            "id": 80,
            "text": "New order created.",
            "created_at": "2019-08-13T22:39:56.000000Z"
        },
        {
            "id": 81,
            "text": "Item #8 added to order #9.",
            "created_at": "2019-08-13T22:40:52.000000Z"
        },
        {
            "id": 82,
            "text": "Order submitted.",
            "created_at": "2019-08-13T22:41:18.000000Z"
        }
    ],
    "files": [
        {
            "id": 24,
            "url": "https://test-downloads.mypromo.com/lfs.pdf",
            "type": "deliverySlip",
            "carrier": null,
            "tracking_code": null,
            "status": "PENDING"
        },
        {
            "id": 25,
            "url": "sftp://test-downloads.mypromo.com/upload/label.pdf",
            "type": "label",
            "carrier": "UPS",
            "tracking_code": "1Z123891378123",
            "status": "PENDING"
        }
    ],
    "shipments": [],
    "created_at": "2019-08-13T22:39:56.000000Z",
    "updated_at": "2019-08-13T22:41:18.000000Z"
}

Manage orders

Get all orders

Get a paged list of all your orders.

Optional filters:

  • from (int, default=0)
  • per_page (int, default=5, max. 15)
  • created_from (date)
  • created_to (date)
  • updated_from (date)
  • updated_to (date)
HTTP Request
GET {{ENDPOINT}}v1/orders?from=0&per_page=5&created_from=2020-02-10&created_to=2020-12-31&updated_from=2020-02-10&updated_to=2020-12-31&pagination=false&reference=abc123&reference2=123xyz
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/orders?from=0&per_page=5&created_from=2020-02-10&created_to=2020-12-31&updated_from=2020-02-10&updated_to=2020-12-31&pagination=false&reference=abc123&reference2=123xyz"
GET %7B%7BENDPOINT%7D%7Dv1/orders?from=0&per_page=5&created_from=2020-02-10&created_to=2020-12-31&updated_from=2020-02-10&updated_to=2020-12-31&pagination=false&reference=abc123&reference2=123xyz HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 200 OK
{
    "data": [
        {
            "id": 9,
            "reference": "order ref",
            "reference2": null,
            "complaint": false,
            "express_production": false,
            "express_shipping": false,
            "shipping_earliest": "2019-08-20T23:59:59.000000Z",
            "shipping_latest": "2019-08-22T23:59:59.000000Z",
            "shipping_late": false,
            "status": "FINISHED",
            "comment": null,
            "callback": {
                "url": "https://downloads.test.mypromo.com/callback.php",
                "authType": "oauth2"
            },
            "generic_label": {
                "url": "https://downloads.test.mypromo.com/genericLabel/{{$guid}}",
                "authType": "oauth2"
            },
            "custom_properties": [
                {
                    "key": "property",
                    "value": "value"
                },
                {
                    "key": "property",
                    "value": "value"
                },
                {
                    "key": "property",
                    "value": "value"
                }
            ],
            "shipper": {
                "id": 26,
                "reference": "ref",
                "company": "Sample Company",
                "department": null,
                "firstname": "Sam",
                "lastname": "Sample",
                "street": "Sample Street 1",
                "care_of": "Street add",
                "zip": "12345",
                "city": "Sample Town",
                "state_code": "NW",
                "district": "District",
                "country_code": "DE",
                "phone": "+4991234567890",
                "fax": null,
                "mobile": null,
                "email": "sam@sample.com",
                "vat_id": null,
                "commercial_register_entry": "Test123"
            },
            "recipient": {
                "id": 28,
                "reference": "ref",
                "company": "Sample Company",
                "department": null,
                "firstname": "Sam",
                "lastname": "Sample",
                "street": "Sample Street 1",
                "care_of": "Street add",
                "zip": "12345",
                "city": "Sample Town",
                "state_code": "NW",
                "district": "District",
                "country_code": "DE",
                "phone": "+491234567890",
                "fax": null,
                "mobile": null,
                "email": "sam@sample.com",
                "vat_id": null,
                "commercial_register_entry": "Test321"
            },
            "export": {
                "id": 27,
                "reference": "ref",
                "company": "Sample Company",
                "department": null,
                "firstname": "Sam",
                "lastname": "Sample",
                "street": "Sample Street 1",
                "care_of": "Street add",
                "zip": "12345",
                "city": "Sample Town",
                "state_code": "NW",
                "district": "District",
                "country_code": "DE",
                "phone": "+491234567890",
                "fax": null,
                "mobile": null,
                "email": "sam@sample.com",
                "vat_id": null,
                "commercial_register_entry": "Test321444",
                "iban": null,
                "bic_or_swift": null,
                "account_holder": null,
                "eori_number": null
            },
            "items": [
                {
                    "id": 8,
                    "reference": "yourItemReference",
                    "quantity": 5,
                    "sku": "TPD123LD02LAXALOP",
                    "type": "FILES",
                    "shipping_earliest": "2019-08-20T23:59:59.000000Z",
                    "shipping_latest": "2019-08-22T23:59:59.000000Z",
                    "shipping_late": false,
                    "status": "FINISHED",
                    "custom_properties": [
                        {
                            "key": "property",
                            "value": "value"
                        },
                        {
                            "key": "property",
                            "value": "value"
                        },
                        {
                            "key": "property",
                            "value": "value"
                        }
                    ],
                    "files": [
                        {
                            "id": 26,
                            "url": "https://test-downloads.mypromo.com/a4.pdf",
                            "type": "front",
                            "status": "DOWNLOADED",
                            "authType": "basic"
                        }
                    ],
                    "designs": [],
                    "customs": {
                        "description": "Printed matter, n.e.s.",
                        "number": "49119900",
                        "origin": "DE",
                        "currency": "EUR",
                        "amount": 10.5
                    }
                }
            ],
            "histories": [
                {
                    "id": 80,
                    "text": "New order created.",
                    "created_at": "2019-08-13T22:39:56.000000Z"
                },
                {
                    "id": 81,
                    "text": "Item #8 added to order #9.",
                    "created_at": "2019-08-13T22:40:52.000000Z"
                },
                {
                    "id": 82,
                    "text": "Order submitted.",
                    "created_at": "2019-08-13T22:41:18.000000Z"
                },
                {
                    "id": 83,
                    "text": "File \"lfs.pdf\": File downloaded.",
                    "created_at": "2019-08-13T22:42:02.000000Z"
                },
                {
                    "id": 84,
                    "text": "File \"label.pdf\": File downloaded.",
                    "created_at": "2019-08-13T22:42:03.000000Z"
                },
                {
                    "id": 85,
                    "text": "Order ready for production.",
                    "created_at": "2019-08-13T22:42:03.000000Z"
                },
                {
                    "id": 86,
                    "text": "Order is now in production.",
                    "created_at": "2019-08-13T22:43:03.000000Z"
                },
                {
                    "id": 87,
                    "text": "Callback for order #9 sent. (HTTP 200)",
                    "created_at": "2019-08-13T22:43:03.000000Z"
                },
                {
                    "id": 88,
                    "text": "Shipment #7 created.",
                    "created_at": "2019-08-13T22:44:03.000000Z"
                },
                {
                    "id": 89,
                    "text": "Callback for package #7 sent. (HTTP 200)",
                    "created_at": "2019-08-13T22:44:15.000000Z"
                },
                {
                    "id": 90,
                    "text": "Order finished.",
                    "created_at": "2019-08-13T22:46:03.000000Z"
                },
                {
                    "id": 91,
                    "text": "Callback for order #9 sent. (HTTP 200)",
                    "created_at": "2019-08-13T22:46:03.000000Z"
                }
            ],
            "files": [
                {
                    "id": 24,
                    "url": "https://test-downloads.mypromo.com/lfs.pdf",
                    "type": "deliverySlip",
                    "carrier": null,
                    "tracking_code": null,
                    "status": "DOWNLOADED",
                    "authType": "basic"
                },
                {
                    "id": 25,
                    "url": "sftp://test-downloads.mypromo.com/upload/label.pdf",
                    "type": "label",
                    "carrier": "UPS",
                    "tracking_code": "1Z123891378123",
                    "status": "DOWNLOADED",
                    "authType": "header"
                }
            ],
            "shipments": [
                {
                    "id": 7,
                    "carrier": "UPS",
                    "tracking_id": "FAKE123CODE",
                    "tracking_url": "http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=FAKE123CODE",
                    "delivered": false,
                    "delivery_earliest": null,
                    "delivery_latest": null,
                    "delivery_late": false,
                    "delivered_date": null,
                    "height": null,
                    "width": null,
                    "depth": null,
                    "weight": null,
                    "status": "SHIPPED",
                    "items": [
                        {
                            "id": 8,
                            "reference": "yourItemReference",
                            "quantity": 3,
                            "sku": "TPD123LD02LAXALOP"
                        }
                    ]
                }
            ],
            "created_at": "2019-08-13T22:39:56.000000Z",
            "updated_at": "2019-08-13T22:46:03.000000Z"
        }
    ],
    "links": {
        "first": "{{ENDPOINT}}v1/orders?page=1",
        "last": "{{ENDPOINT}}v1/orders?page=2",
        "prev": null,
        "next": "{{ENDPOINT}}v1/orders?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 2,
        "path": "{{ENDPOINT}}v1/orders",
        "per_page": "5",
        "to": 5,
        "total": 9
    }
}

Get order by id

Get a repesentation of a specific order with all details (e.g. items, packages, history etc.).

HTTP Request
GET {{ENDPOINT}}v1/orders/{{ORDERID}}
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/orders/{{ORDERID}}"
GET %7B%7BENDPOINT%7D%7Dv1/orders/%7B%7BORDERID%7D%7D HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 200 OK
{
    "id": 9,
    "reference": "order ref",
    "reference2": null,
    "complaint": false,
    "express_production": false,
    "express_shipping": false,
    "shipping_earliest": "2019-08-20T23:59:59.000000Z",
    "shipping_latest": "2019-08-22T23:59:59.000000Z",
    "shipping_late": false,
    "status": "FINISHED",
    "comment": null,
    "callback": {
        "url": "https://downloads.test.mypromo.com/callback.php"
    },
    "generic_label": {
        "url": "https://downloads.test.mypromo.com/genericLabel/{{$guid}}",
        "authType": "oauth2"
    },
    "custom_properties": [
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        },
        {
            "key": "property",
            "value": "value"
        }
    ],
    "shipper": {
        "id": 26,
        "reference": "ref",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+4991234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": null,
        "commercial_register_entry": "Test123"
    },
    "recipient": {
        "id": 28,
        "reference": "ref",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+491234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": null,
        "commercial_register_entry": "Test321"
    },
    "export": {
        "id": 27,
        "reference": "ref",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+491234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": null,
        "commercial_register_entry": "Test321444",
        "iban": null,
        "bic_or_swift": null,
        "account_holder": null,
        "eori_number": null
    },
    "items": [
        {
            "id": 8,
            "reference": "yourItemReference",
            "quantity": 5,
            "sku": "TPD123LD02LAXALOP",
            "type": "FILES",
            "shipping_earliest": null,
            "shipping_latest": null,
            "shipping_late": false,
            "status": "FINISHED",
            "custom_properties": [
                {
                    "key": "property",
                    "value": "value"
                },
                {
                    "key": "property",
                    "value": "value"
                },
                {
                    "key": "property",
                    "value": "value"
                }
            ],
            "files": [
                {
                    "id": 26,
                    "url": "https://test-downloads.mypromo.com/a4.pdf",
                    "type": "front",
                    "status": "DOWNLOADED"
                }
            ],
            "designs": [],
            "customs": {
                "description": "Printed matter, n.e.s.",
                "number": "49119900",
                "origin": "DE",
                "currency": "EUR",
                "amount": 10.5
            }
        }
    ],
    "histories": [
        {
            "id": 80,
            "text": "New order created.",
            "created_at": "2019-08-13T22:39:56.000000Z"
        },
        {
            "id": 81,
            "text": "Item #8 added to order #9.",
            "created_at": "2019-08-13T22:40:52.000000Z"
        },
        {
            "id": 82,
            "text": "Order submitted.",
            "created_at": "2019-08-13T22:41:18.000000Z"
        },
        {
            "id": 83,
            "text": "File \"lfs.pdf\": File downloaded.",
            "created_at": "2019-08-13T22:42:02.000000Z"
        },
        {
            "id": 84,
            "text": "File \"label.pdf\": File downloaded.",
            "created_at": "2019-08-13T22:42:03.000000Z"
        },
        {
            "id": 85,
            "text": "Order ready for production.",
            "created_at": "2019-08-13T22:42:03.000000Z"
        },
        {
            "id": 86,
            "text": "Order is now in production.",
            "created_at": "2019-08-13T22:43:03.000000Z"
        },
        {
            "id": 87,
            "text": "Callback for order #9 sent. (HTTP 200)",
            "created_at": "2019-08-13T22:43:03.000000Z"
        },
        {
            "id": 88,
            "text": "Shipment #7 created.",
            "created_at": "2019-08-13T22:44:03.000000Z"
        },
        {
            "id": 89,
            "text": "Callback for package #7 sent. (HTTP 200)",
            "created_at": "2019-08-13T22:44:15.000000Z"
        },
        {
            "id": 90,
            "text": "Order finished.",
            "created_at": "2019-08-13T22:46:03.000000Z"
        },
        {
            "id": 91,
            "text": "Callback for order #9 sent. (HTTP 200)",
            "created_at": "2019-08-13T22:46:03.000000Z"
        }
    ],
    "files": [
        {
            "id": 24,
            "url": "https://test-downloads.mypromo.com/lfs.pdf",
            "type": "deliverySlip",
            "carrier": null,
            "tracking_code": null,
            "status": "DOWNLOADED",
            "authType": "basic"
        },
        {
            "id": 25,
            "url": "sftp://test-downloads.mypromo.com/upload/label.pdf",
            "type": "label",
            "carrier": "UPS",
            "tracking_code": "1Z123891378123",
            "status": "DOWNLOADED",
            "authType": "header"
        }
    ],
    "shipments": [
        {
            "id": 7,
            "carrier": "UPS",
            "tracking_id": "FAKE123CODE",
            "tracking_url": "http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=FAKE123CODE",
            "delivered": false,
            "delivery_earliest": null,
            "delivery_latest": null,
            "delivery_late": false,
            "delivered_date": null,
            "height": null,
            "width": null,
            "depth": null,
            "weight": null,
            "status": "SHIPPED",
            "force": false,
            "items": [
                {
                    "id": 8,
                    "reference": "yourItemReference",
                    "quantity": 3,
                    "sku": "TPD123LD02LAXALOP"
                }
            ]
        }
    ],
    "created_at": "2019-08-13T22:39:56.000000Z",
    "updated_at": "2019-08-13T22:46:03.000000Z"
}

Update order by id

While an order has not been sent to production you can partially modify it.

Note: Route not supported yet.

HTTP Request
PATCH {{ENDPOINT}}v1/orders/{{ORDERID}}
Headers
Content-Type
application/json
Accept
application/json
PayLoad
{
    "express_shipping": true
}
Example request
curl -X PATCH -H "Content-Type: application/json" -H "Accept: application/json" -d '{
	"express_shipping": true
}' "{{ENDPOINT}}v1/orders/{{ORDERID}}"
PATCH %7B%7BENDPOINT%7D%7Dv1/orders/%7B%7BORDERID%7D%7D HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json

{
	"express_shipping": true
}

Cancel order by id

While an order has not been sent to production you can cancel it.

HTTP Request
PATCH {{ENDPOINT}}v1/orders/{{ORDERID}}/cancel
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X PATCH -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/orders/{{ORDERID}}/cancel"
PATCH %7B%7BENDPOINT%7D%7Dv1/orders/%7B%7BORDERID%7D%7D/cancel HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 422 Unprocessable Entity
{
    "message": "You cannot edit a processed order."
}
Status 200 OK
{
    "id": 10,
    "reference": "order ref",
    "reference2": null,
    "complaint": false,
    "express_production": false,
    "express_shipping": false,
    "shipping_earliest": null,
    "shipping_latest": null,
    "shipping_late": false,
    "status": "CANCELED",
    "comment": null,
    "shipper": {
        "id": 29,
        "reference": "ref",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+4991234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": null,
        "commercial_register_entry": "Test123"
    },
    "recipient": {
        "id": 31,
        "reference": "ref",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+491234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": null,
        "commercial_register_entry": "Test321"
    },
    "export": {
        "id": 30,
        "reference": "ref",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+491234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": null,
        "commercial_register_entry": "Test321444",
        "iban": null,
        "bic_or_swift": null,
        "account_holder": null,
        "eori_number": null
    },
    "items": [],
    "histories": [
        {
            "id": 92,
            "text": "New order created.",
            "created_at": "2019-08-13T22:54:35.000000Z"
        },
        {
            "id": 93,
            "text": "Order canceled.",
            "created_at": "2019-08-13T22:54:44.000000Z"
        }
    ],
    "files": [
        {
            "id": 27,
            "url": "https://test-downloads.mypromo.com/lfs.pdf",
            "type": "deliverySlip",
            "carrier": null,
            "tracking_code": null,
            "status": "PENDING"
        },
        {
            "id": 28,
            "url": "sftp://test-downloads.mypromo.com/upload/label.pdf",
            "type": "label",
            "carrier": "UPS",
            "tracking_code": "1Z123891378123",
            "status": "PENDING"
        }
    ],
    "shipments": [],
    "created_at": "2019-08-13T22:54:35.000000Z",
    "updated_at": "2019-08-13T22:54:44.000000Z"
}

Products

Get details about available products, SKUs, availability and stock.

Get products

Get a paged list of all available products and details.

  • For Merchants: All available products from all fulfillers
  • For Fulfillers: Products of the requesting client only

Mandatory filters:

  • shipping_from (iso2 country code (e.g. DE, AT, UK, US, …), default=DE)

Optional filters:

  • from (int, default=0)
  • per_page (int, default=5)
  • sku OR sku_fulfiller (string)
  • currency (iso3, default=EUR)
  • lang (iso2 lang code (e.g. DE, EN, …), default=EN)
  • search (string)
  • available (bool)
  • sku (string)

Some details:
* active: Product is available
* availabe: Merchant: Product is set to active for sync to sales channels. Fulfiller: Product is orderable
* availability: Merchant: Shows from which fulfillers the product is available and the current status of contract. Fulfillers: Shows own details.
* test_product: internal use or for testing (will not be produced)
* sample_product: Sample products are assigned to their customizable version (see relations)
* tier_price_qty_only: if set to false any qty between min and max can be orderd, else the qty of the tiers can be ordered
* personalized: if set to true normally the editor is available and print file is required, else its a product taken from stock
* parts: product parts… not available yet

HTTP Request
GET {{ENDPOINT}}v1/products?from=1&per_page=15&shipping_from=DE&available=true&lang=DE¤cy=EUR&pagination=false
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/products?from=1&per_page=15&shipping_from=DE&available=true&lang=DE¤cy=EUR&pagination=false"
GET %7B%7BENDPOINT%7D%7Dv1/products?from=1&per_page=15&shipping_from=DE&available=true&lang=DE¤cy=EUR&pagination=false HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 200 OK
{
    "data": [
        {
            "id": 1,
            "lang": "DE",
            "descriptions": {
                "name": "Testproduct Group",
                "overwritten": false
            },
            "categories": [
                {
                    "name": "Büro"
                },
                {
                    "name": "Büro/Schreibgeräte"
                }
            ],
            "media": {
                "image": "https://storage.mypromo.com/unique_seo_url_10.jpg",
                "video": "https://storage.mypromo.com/unique_seo_url_40.mp4"
            },
            "variants": [
                {
                    "id": 10,
                    "sku": "TESTPRODUCT123",
                    "gtin": null,
                    "active": true,
                    "available": true,
                    "availability": {
                        "clients": [
                            {
                                "id": 1,
                                "type": "fulfiller",
                                "name": "Fulfiller",
                                "sku_fulfiller": "F-TESTPRODUCT123",
                                "available": true,
                                "stock": {
                                    "managed": false,
                                    "qty": 0
                                },
                                "shipping_from": "DE",
                                "contract_id": "F1",
                                "contract": {
                                    "status": "ACCEPTED",
                                    "requested_at": "2021-01-11T15:42:36.000000Z",
                                    "accepted_at": "2021-01-11T15:42:36.000000Z",
                                    "canceled_at": null,
                                    "declined_at": null
                                }
                            }
                        ]
                    },
                    "test_product": true,
                    "sample_product": false,
                    "personalized": true,
                    "descriptions": {
                        "name": "Testprodukt",
                        "description": "Beschreibung Testprodukt",
                        "description_short": null,
                        "description_secondary": "Beschreibung zwei Testprodukt",
                        "overwritten": false
                    },
                    "properties": [
                        {
                            "property": "width",
                            "value": 210
                        },
                        {
                            "property": "height",
                            "value": 297
                        },
                        {
                            "property": "depth",
                            "value": 1
                        },
                        {
                            "property": "weight",
                            "value": 5
                        },
                        {
                            "property": "color",
                            "value": "blue"
                        },
                        {
                            "property": "material",
                            "value": "Glossy plastic"
                        },
                        {
                            "property": "superdark",
                            "value": false
                        },
                        {
                            "property": "diameter",
                            "value": 3.14159265359
                        }
                    ],
                    "parts": [
                        {
                            "id": 40,
                            "name": "Body of Pen",
                            "key": "body",
                            "printing_method": "digital",
                            "requirements": {
                                "width": 120,
                                "height": 5,
                                "bleed": 0,
                                "pages": 1
                            }
                        },
                        {
                            "id": 40,
                            "name": "Clip of Pen",
                            "key": "clip",
                            "printing_method": "engraving",
                            "requirements": {
                                "width": 40,
                                "height": 10,
                                "bleed": 0,
                                "pages": 1
                            }
                        }
                    ],
                    "media": {
                        "image": "https://storage.mypromo.com/unique_seo_url_1.jpg",
                        "additional_images": [
                            "https://storage.mypromo.com/unique_seo_url_2.jpg",
                            "https://storage.mypromo.com/unique_seo_url_3.jpg"
                        ],
                        "video": "https://storage.mypromo.com/unique_seo_url_4.mp4",
                        "additional_videos": [
                            "https://storage.mypromo.com/unique_seo_url_5.mp4",
                            "https://storage.mypromo.com/unique_seo_url_6.mp4"
                        ],
                        "download_pdf": null,
                        "download_indesign": null,
                        "download_datasheet": null
                    },
                    "prices": {
                        "currency": "EUR",
                        "purchase_prices": [
                            {
                                "qty": 50,
                                "price": 14.99
                            },
                            {
                                "qty": 100,
                                "price": 12.99
                            },
                            {
                                "qty": 200,
                                "price": 9.99
                            }
                        ],
                        "recommended_retail_prices": [
                            {
                                "qty": 50,
                                "price": 114.99
                            },
                            {
                                "qty": 100,
                                "price": 112.99
                            },
                            {
                                "qty": 200,
                                "price": 19.99
                            }
                        ],
                        "sales_prices": [
                            {
                                "qty": 50,
                                "price": 100.99
                            },
                            {
                                "qty": 100,
                                "price": 100.99
                            },
                            {
                                "qty": 200,
                                "price": 14.99
                            }
                        ]
                    },
                    "rules": {
                        "order_min_qty": 50,
                        "order_max_qty": 5000,
                        "tier_price_qty_only": true
                    },
                    "shipping": {
                        "shipping_from": "DE",
                        "shipping_earliest": 3,
                        "shipping_latest": 5,
                        "express_available": false
                    },
                    "relations": {
                        "related": [
                            {
                                "id": 400,
                                "sku": "DAMNGOODPRODUCT",
                                "descriptions": {
                                    "name": "Testprodukt",
                                    "description": "Beschreibung Testprodukt",
                                    "description_short": null,
                                    "description_secondary": "Beschreibung zwei Testprodukt",
                                    "overwritten": false
                                }
                            },
                            {
                                "id": 401,
                                "sku": "FUNNYPRODUCT",
                                "descriptions": {
                                    "name": "Testprodukt",
                                    "description": "Beschreibung Testprodukt",
                                    "description_short": null,
                                    "description_secondary": "Beschreibung zwei Testprodukt",
                                    "overwritten": false
                                }
                            }
                        ],
                        "up-selling": [
                            {
                                "id": 30,
                                "sku": "DAMNGOODPRODUCT",
                                "descriptions": {
                                    "name": "Testprodukt",
                                    "description": "Beschreibung Testprodukt",
                                    "description_short": null,
                                    "description_secondary": "Beschreibung zwei Testprodukt",
                                    "overwritten": false
                                }
                            },
                            {
                                "id": 76,
                                "sku": "FUNNYPRODUCT",
                                "descriptions": {
                                    "name": "Testprodukt",
                                    "description": "Beschreibung Testprodukt",
                                    "description_short": null,
                                    "description_secondary": "Beschreibung zwei Testprodukt",
                                    "overwritten": false
                                }
                            }
                        ],
                        "cross-selling": [
                            {
                                "id": 30,
                                "sku": "DAMNGOODPRODUCT",
                                "descriptions": {
                                    "name": "Testprodukt",
                                    "description": "Beschreibung Testprodukt",
                                    "description_short": null,
                                    "description_secondary": "Beschreibung zwei Testprodukt",
                                    "overwritten": false
                                }
                            },
                            {
                                "id": 76,
                                "sku": "FUNNYPRODUCT",
                                "descriptions": {
                                    "name": "Testprodukt",
                                    "description": "Beschreibung Testprodukt",
                                    "description_short": null,
                                    "description_secondary": "Beschreibung zwei Testprodukt",
                                    "overwritten": false
                                }
                            }
                        ],
                        "samples": [
                            {
                                "id": 156,
                                "sku": "TESTPRODUCT-SAMPLE",
                                "descriptions": {
                                    "name": "Testprodukt",
                                    "description": "Beschreibung Testprodukt",
                                    "description_short": null,
                                    "description_secondary": "Beschreibung zwei Testprodukt",
                                    "overwritten": false
                                }
                            }
                        ]
                    },
                    "editor": {
                        "available": true,
                        "intents": [
                            "upload",
                            "customize"
                        ]
                    },
                    "created_at": "2020-02-25T23:59:59.000000Z",
                    "updated_at": "2020-02-25T23:59:59.000000Z"
                }
            ],
            "created_at": "2020-02-25T23:59:59.000000Z",
            "updated_at": "2020-02-25T23:59:59.000000Z"
        }
    ],
    "links": {
        "first": "{{ENDPOINT}}v1/products?page=1",
        "last": "{{ENDPOINT}}v1/products?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "{{ENDPOINT}}v1/products",
        "per_page": "5",
        "to": 1,
        "total": 1
    }
}
Status 200 OK
{
    "data": [
        {
            "id": 1,
            "lang": "DE",
            "descriptions": {
                "name": "Testproduct Group"
            },
            "categories": [
                {
                    "name": "Büro"
                },
                {
                    "name": "Büro/Schreibgeräte"
                }
            ],
            "media": {
                "image": "https://storage.mypromo.com/unique_seo_url_10.jpg",
                "video": "https://storage.mypromo.com/unique_seo_url_40.mp4"
            },
            "variants": [
                {
                    "id": 10,
                    "sku": "TESTPRODUCT123",
                    "gtin": null,
                    "active": true,
                    "available": true,
                    "availability": {
                        "clients": [
                            {
                                "id": 1,
                                "type": "fulfiller",
                                "name": "Fulfiller",
                                "sku_fulfiller": "F-TESTPRODUCT123",
                                "available": true,
                                "stock": {
                                    "managed": false,
                                    "qty": 0
                                },
                                "shipping_from": "DE",
                                "contract_id": "F1"
                            }
                        ]
                    },
                    "test_product": true,
                    "sample_product": false,
                    "personalized": true,
                    "descriptions": {
                        "name": "Testprodukt",
                        "description": "Beschreibung Testprodukt",
                        "description_short": null,
                        "description_secondary": "Beschreibung zwei Testprodukt"
                    },
                    "properties": [
                        {
                            "property": "width",
                            "value": 210
                        },
                        {
                            "property": "height",
                            "value": 297
                        },
                        {
                            "property": "depth",
                            "value": 1
                        },
                        {
                            "property": "weight",
                            "value": 5
                        },
                        {
                            "property": "color",
                            "value": "blue"
                        },
                        {
                            "property": "material",
                            "value": "Glossy plastic"
                        },
                        {
                            "property": "superdark",
                            "value": false
                        },
                        {
                            "property": "diameter",
                            "value": 3.14159265359
                        }
                    ],
                    "parts": [
                        {
                            "id": 40,
                            "name": "Body of Pen",
                            "key": "body",
                            "printing_method": "digital",
                            "requirements": {
                                "width": 120,
                                "height": 5,
                                "bleed": 0,
                                "pages": 1
                            }
                        },
                        {
                            "id": 40,
                            "name": "Clip of Pen",
                            "key": "clip",
                            "printing_method": "engraving",
                            "requirements": {
                                "width": 40,
                                "height": 10,
                                "bleed": 0,
                                "pages": 1
                            }
                        }
                    ],
                    "media": {
                        "image": "https://storage.mypromo.com/unique_seo_url_1.jpg",
                        "additional_images": [
                            "https://storage.mypromo.com/unique_seo_url_2.jpg",
                            "https://storage.mypromo.com/unique_seo_url_3.jpg"
                        ],
                        "video": "https://storage.mypromo.com/unique_seo_url_4.mp4",
                        "additional_videos": [
                            "https://storage.mypromo.com/unique_seo_url_5.mp4",
                            "https://storage.mypromo.com/unique_seo_url_6.mp4"
                        ],
                        "download_pdf": null,
                        "download_indesign": null,
                        "download_datasheet": null
                    },
                    "prices": {
                        "currency": "EUR",
                        "purchase_prices": [
                            {
                                "qty": 50,
                                "price": 14.99
                            },
                            {
                                "qty": 100,
                                "price": 12.99
                            },
                            {
                                "qty": 200,
                                "price": 9.99
                            }
                        ],
                        "recommended_retail_prices": [
                            {
                                "qty": 50,
                                "price": 114.99
                            },
                            {
                                "qty": 100,
                                "price": 112.99
                            },
                            {
                                "qty": 200,
                                "price": 19.99
                            }
                        ],
                        "sales_prices": [
                            {
                                "qty": 50,
                                "price": 100.99
                            },
                            {
                                "qty": 100,
                                "price": 100.99
                            },
                            {
                                "qty": 200,
                                "price": 14.99
                            }
                        ]
                    },
                    "rules": {
                        "order_min_qty": 50,
                        "order_max_qty": 5000,
                        "tier_price_qty_only": true
                    },
                    "shipping": {
                        "shipping_from": "DE",
                        "shipping_earliest": 3,
                        "shipping_latest": 5,
                        "express_available": false
                    },
                    "relations": {
                        "related": [
                            {
                                "id": 400,
                                "sku": "DAMNGOODPRODUCT",
                                "descriptions": {
                                    "name": "Testprodukt",
                                    "description": "Beschreibung Testprodukt",
                                    "description_short": null,
                                    "description_secondary": "Beschreibung zwei Testprodukt"
                                }
                            },
                            {
                                "id": 401,
                                "sku": "FUNNYPRODUCT",
                                "descriptions": {
                                    "name": "Testprodukt",
                                    "description": "Beschreibung Testprodukt",
                                    "description_short": null,
                                    "description_secondary": "Beschreibung zwei Testprodukt"
                                }
                            }
                        ],
                        "up-selling": [
                            {
                                "id": 30,
                                "sku": "DAMNGOODPRODUCT",
                                "descriptions": {
                                    "name": "Testprodukt",
                                    "description": "Beschreibung Testprodukt",
                                    "description_short": null,
                                    "description_secondary": "Beschreibung zwei Testprodukt"
                                }
                            },
                            {
                                "id": 76,
                                "sku": "FUNNYPRODUCT",
                                "descriptions": {
                                    "name": "Testprodukt",
                                    "description": "Beschreibung Testprodukt",
                                    "description_short": null,
                                    "description_secondary": "Beschreibung zwei Testprodukt"
                                }
                            }
                        ],
                        "cross-selling": [
                            {
                                "id": 30,
                                "sku": "DAMNGOODPRODUCT",
                                "descriptions": {
                                    "name": "Testprodukt",
                                    "description": "Beschreibung Testprodukt",
                                    "description_short": null,
                                    "description_secondary": "Beschreibung zwei Testprodukt"
                                }
                            },
                            {
                                "id": 76,
                                "sku": "FUNNYPRODUCT",
                                "descriptions": {
                                    "name": "Testprodukt",
                                    "description": "Beschreibung Testprodukt",
                                    "description_short": null,
                                    "description_secondary": "Beschreibung zwei Testprodukt"
                                }
                            }
                        ],
                        "samples": [
                            {
                                "id": 156,
                                "sku": "TESTPRODUCT-SAMPLE",
                                "descriptions": {
                                    "name": "Testprodukt",
                                    "description": "Beschreibung Testprodukt",
                                    "description_short": null,
                                    "description_secondary": "Beschreibung zwei Testprodukt"
                                }
                            }
                        ]
                    },
                    "editor": {
                        "available": true,
                        "intents": [
                            "upload",
                            "customize"
                        ]
                    },
                    "created_at": "2020-02-25T23:59:59.000000Z",
                    "updated_at": "2020-02-25T23:59:59.000000Z"
                }
            ],
            "created_at": "2020-02-25T23:59:59.000000Z",
            "updated_at": "2020-02-25T23:59:59.000000Z"
        }
    ],
    "links": {
        "first": "{{ENDPOINT}}v1/products?page=1",
        "last": "{{ENDPOINT}}v1/products?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "{{ENDPOINT}}v1/products",
        "per_page": "5",
        "to": 1,
        "total": 1
    }
}

Get product by id

TBD: split in merchant | fulfiller … see availability: just for merchants

Get details of a specified product.
PRODUCTID can be a mother or variant.
If its a variant you will get the mother with all variants containing the product id.

Mandatory filters:

  • none

Optional filters:

  • lang (iso2 lang code (e.g. DE, EN, …), default=EN)
HTTP Request
GET {{ENDPOINT}}v1/products/{{PRODUCTID}}?lang=DE
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/products/{{PRODUCTID}}?lang=DE"
GET %7B%7BENDPOINT%7D%7Dv1/products/%7B%7BPRODUCTID%7D%7D?lang=DE HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 404 Not Found
{
    "message": "Not found."
}
Status 200 OK
{
    "id": 1,
    "lang": "DE",
    "descriptions": {
        "name": "Testproduct Group",
        "overwritten": false
    },
    "categories": [
        {
            "name": "Büro"
        },
        {
            "name": "Büro/Schreibgeräte"
        }
    ],
    "media": {
        "image": "https://storage.mypromo.com/unique_seo_url_1.jpg",
        "video": "https://storage.mypromo.com/unique_seo_url_4.mp4"
    },
    "variants": [
        {
            "id": 10,
            "sku": "TESTPRODUCT123",
            "gtin": null,
            "active": false,
            "available": true,
            "availability": {
                "clients": [
                    {
                        "id": 1,
                        "type": "fulfiller",
                        "name": "Fulfiller x",
                        "shipping_from": "DE",
                        "contract_id": "F012",
                        "contract": {
                            "status": "accepted",
                            "requested_at": "2020-02-23T23:59:59.000000Z",
                            "accepted_at": "2020-02-25T23:59:59.000000Z",
                            "canceled_at": null
                        }
                    },
                    {
                        "id": 2,
                        "type": "fulfiller",
                        "name": "Fulfiller y",
                        "shipping_from": "FR",
                        "contract_id": "F014",
                        "contract": {
                            "status": "declined",
                            "requested_at": "2020-02-25T23:59:59.000000Z",
                            "accepted_at": null,
                            "canceled_at": null
                        }
                    }
                ]
            },
            "test_product": true,
            "sample_product": false,
            "personalized": true,
            "descriptions": {
                "name": "Testprodukt",
                "description": "Beschreibung Testprodukt",
                "description_short": null,
                "description_secondary": "Beschreibung zwei Testprodukt",
                "overwritten": false
            },
            "properties": [
                {
                    "property": "width",
                    "value": 210
                },
                {
                    "property": "height",
                    "value": 297
                },
                {
                    "property": "depth",
                    "value": 1
                },
                {
                    "property": "weight",
                    "value": 5
                },
                {
                    "property": "color",
                    "value": "blue"
                },
                {
                    "property": "material",
                    "value": "Glossy plastic"
                },
                {
                    "property": "superdark",
                    "value": false
                },
                {
                    "property": "diameter",
                    "value": 3.14159265359
                }
            ],
            "parts": [
                {
                    "id": 40,
                    "name": "Body of Pen",
                    "key": "body",
                    "printing_method": "digital",
                    "requirements": {
                        "width": 120,
                        "height": 5,
                        "bleed": 0,
                        "pages": 1
                    }
                },
                {
                    "id": 40,
                    "name": "Clip of Pen",
                    "key": "clip",
                    "printing_method": "engraving",
                    "requirements": {
                        "width": 40,
                        "height": 10,
                        "bleed": 0,
                        "pages": 1
                    }
                }
            ],
            "media": {
                "image": "https://storage.mypromo.com/unique_seo_url_1.jpg",
                "additional_images": [
                    "https://storage.mypromo.com/unique_seo_url_2.jpg",
                    "https://storage.mypromo.com/unique_seo_url_3.jpg"
                ],
                "video": "https://storage.mypromo.com/unique_seo_url_4.mp4",
                "additional_videos": [
                    "https://storage.mypromo.com/unique_seo_url_5.mp4",
                    "https://storage.mypromo.com/unique_seo_url_6.mp4"
                ],
                "download_pdf": null,
                "download_indesign": null,
                "download_datasheet": null
            },
            "prices": {
                "currency": "EUR",
                "purchase_prices": [
                    {
                        "qty": 50,
                        "price": 14.99
                    },
                    {
                        "qty": 100,
                        "price": 12.99
                    },
                    {
                        "qty": 200,
                        "price": 9.99
                    }
                ],
                "recommended_retail_prices": [
                    {
                        "qty": 50,
                        "price": 114.99
                    },
                    {
                        "qty": 100,
                        "price": 112.99
                    },
                    {
                        "qty": 200,
                        "price": 19.99
                    }
                ],
                "sales_prices": [
                    {
                        "qty": 50,
                        "price": 100.99
                    },
                    {
                        "qty": 100,
                        "price": 100.99
                    },
                    {
                        "qty": 200,
                        "price": 14.99
                    }
                ]
            },
            "rules": {
                "order_min_qty": 50,
                "order_max_qty": 5000,
                "tier_price_qty_only": true
            },
            "shipping": {
                "shipping_from": "DE",
                "shipping_earliest": 3,
                "shipping_latest": 5,
                "express_available": false
            },
            "relations": {
                "related": [
                    {
                        "id": 400,
                        "sku": "DAMNGOODPRODUCT",
                        "descriptions": {
                            "name": "Testprodukt",
                            "description": "Beschreibung Testprodukt",
                            "description_short": null,
                            "description_secondary": "Beschreibung zwei Testprodukt",
                            "overwritten": false
                        }
                    },
                    {
                        "id": 401,
                        "sku": "FUNNYPRODUCT",
                        "descriptions": {
                            "name": "Testprodukt",
                            "description": "Beschreibung Testprodukt",
                            "description_short": null,
                            "description_secondary": "Beschreibung zwei Testprodukt",
                            "overwritten": false
                        }
                    }
                ],
                "up-selling": [
                    {
                        "id": 30,
                        "sku": "DAMNGOODPRODUCT",
                        "descriptions": {
                            "name": "Testprodukt",
                            "description": "Beschreibung Testprodukt",
                            "description_short": null,
                            "description_secondary": "Beschreibung zwei Testprodukt",
                            "overwritten": false
                        }
                    },
                    {
                        "id": 76,
                        "sku": "FUNNYPRODUCT",
                        "descriptions": {
                            "name": "Testprodukt",
                            "description": "Beschreibung Testprodukt",
                            "description_short": null,
                            "description_secondary": "Beschreibung zwei Testprodukt",
                            "overwritten": false
                        }
                    }
                ],
                "cross-selling": [
                    {
                        "id": 30,
                        "sku": "DAMNGOODPRODUCT",
                        "descriptions": {
                            "name": "Testprodukt",
                            "description": "Beschreibung Testprodukt",
                            "description_short": null,
                            "description_secondary": "Beschreibung zwei Testprodukt",
                            "overwritten": false
                        }
                    },
                    {
                        "id": 76,
                        "sku": "FUNNYPRODUCT",
                        "descriptions": {
                            "name": "Testprodukt",
                            "description": "Beschreibung Testprodukt",
                            "description_short": null,
                            "description_secondary": "Beschreibung zwei Testprodukt",
                            "overwritten": false
                        }
                    }
                ],
                "samples": [
                    {
                        "id": 156,
                        "sku": "TESTPRODUCT-SAMPLE",
                        "descriptions": {
                            "name": "Testprodukt",
                            "description": "Beschreibung Testprodukt",
                            "description_short": null,
                            "description_secondary": "Beschreibung zwei Testprodukt",
                            "overwritten": false
                        }
                    }
                ]
            },
            "editor": {
                "available": true,
                "intents": [
                    "upload",
                    "customize"
                ]
            },
            "created_at": "2020-02-25T23:59:59.000000Z",
            "updated_at": "2020-02-25T23:59:59.000000Z"
        }
    ],
    "created_at": "2020-02-25T23:59:59.000000Z",
    "updated_at": "2020-02-25T23:59:59.000000Z"
}

Get inventory for fulfillers

Get a paged list of all products and their availability and stocks.

Optional filters:

  • from (int, default=0)
  • per_page (int, default=5)
  • sku OR sku_fulfiller (string)
HTTP Request
GET {{ENDPOINT}}v1/inventory?from=0&per_page=250&sku=MP1234567890&sku_fulfiller=999999999&pagination=false
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/inventory?from=0&per_page=250&sku=MP1234567890&sku_fulfiller=999999999&pagination=false"
GET %7B%7BENDPOINT%7D%7Dv1/inventory?from=0&per_page=250&sku=MP1234567890&sku_fulfiller=999999999&pagination=false HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 200 OK
{
    "data": [
        {
            "sku": "TESTPRODUCT123",
            "sku_fulfiller": "TEST Prod-26",
            "available": true,
            "stock": {
                "managed": true,
                "qty": 14500
            }
        },
        {
            "sku": "TESTPRODUCT555",
            "sku_fulfiller": "test-abc",
            "available": true,
            "stock": {
                "managed": false,
                "qty": null
            }
        },
        {
            "sku": "TESTPRODUCT999",
            "sku_fulfiller": null,
            "available": true,
            "stock": {
                "managed": true,
                "qty": 45010
            }
        },
        {
            "sku": "TESTPRODUCT777",
            "sku_fulfiller": "Test Product 777",
            "available": true,
            "stock": {
                "managed": true,
                "qty": 0
            }
        }
    ],
    "links": {
        "first": "{{ENDPOINT}}v1/inventory?page=1",
        "last": "{{ENDPOINT}}v1/inventory?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "{{ENDPOINT}}v1/inventory",
        "per_page": "5",
        "to": 1,
        "total": 3
    }
}

Get inventory for merchants

Get a paged list of all products and their availability and stocks.

Optional filters:

  • from (int, default=0)
  • per_page (int, default=5)
  • sku (string)
  • shipping_from (iso2, default=DE)
HTTP Request
GET {{ENDPOINT}}v1/inventory?from=0&per_page=250&sku=MP1234567890&shipping_from=DE&pagination=false
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/inventory?from=0&per_page=250&sku=MP1234567890&shipping_from=DE&pagination=false"
GET %7B%7BENDPOINT%7D%7Dv1/inventory?from=0&per_page=250&sku=MP1234567890&shipping_from=DE&pagination=false HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 200 OK
{
    "data": [
        {
            "sku": "TESTPRODUCT123",
            "available": true,
            "stock": {
                "managed": true,
                "qty": 14500
            }
        },
        {
            "sku": "TESTPRODUCT555",
            "available": true,
            "stock": {
                "managed": false,
                "qty": null
            }
        },
        {
            "sku": "TESTPRODUCT999",
            "available": true,
            "stock": {
                "managed": true,
                "qty": 45010
            }
        },
        {
            "sku": "TESTPRODUCT777",
            "available": true,
            "stock": {
                "managed": true,
                "qty": 0
            }
        }
    ],
    "links": {
        "first": "{{ENDPOINT}}v1/inventory?page=1",
        "last": "{{ENDPOINT}}v1/inventory?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "{{ENDPOINT}}v1/inventory",
        "per_page": "5",
        "to": 1,
        "total": 3
    }
}

Patch inventory for fulfillers

Update availability and stocks in batches.

You can use sku or sku_fulfiller (not both).
You can update availability or stock only or both together.
If you set a sku to not available (false) the stock details will be kept but the product can not be ordered anymore.

Requests are limited to 500 entries.

HTTP Request
PATCH {{ENDPOINT}}v1/inventory
Headers
Content-Type
application/json
Accept
application/json
PayLoad
{
    "callback": {
        "url": "https://downloads.test.mypromo.com:10433/callback.php",
        "auth": {
            "oauth1": {
                "username": "user",
                "password": "pass",
                "auth_url": "https://myshop.com/api/auth"
            }
        }
    },
    "data": [
        {
            "sku": "TESTPRODUCT123",
            "sku_fulfiller": "TEST Prod-26",
            "available": true,
            "stock": {
                "managed": true,
                "is_in_stock": true,
                "qty": 14500
            }
        },
        {
            "sku": "TESTPRODUCT555",
            "sku_fulfiller": "TEST Prod-555",
            "available": true,
            "stock": {
                "managed": false,
                "is_in_stock": false,
                "qty": null
            }
        },
        {
            "sku": "TESTPRODUCT999",
            "sku_fulfiller": "TEST Prod 999",
            "available": true,
            "stock": {
                "managed": true,
                "is_in_stock": true,
                "qty": 45010
            }
        },
        {
            "sku": "TESTPRODUCT777",
            "sku_fulfiller": "TEST 777",
            "available": true,
            "stock": {
                "managed": true,
                "is_in_stock": true,
                "qty": 0
            }
        }
    ]
}
Example request
curl -X PATCH -H "Content-Type: application/json" -H "Accept: application/json" -d '{
	"callback": {
        "url": "https://downloads.test.mypromo.com:10433/callback.php",
        "auth": {
            "oauth1": {
                "username": "user",
                "password": "pass",
                "auth_url": "https://myshop.com/api/auth"
            }
        }
    },
    "data": [
        {
            "sku": "TESTPRODUCT123",
            "sku_fulfiller": "TEST Prod-26",
            "available": true,
            "stock": {
                "managed": true,
                "is_in_stock": true,
                "qty": 14500
            }
        },
        {
            "sku": "TESTPRODUCT555",
            "sku_fulfiller": "TEST Prod-555",
            "available": true,
            "stock": {
                "managed": false,
                "is_in_stock": false,
                "qty": null
            }
        },
        {
            "sku": "TESTPRODUCT999",
            "sku_fulfiller": "TEST Prod 999",
            "available": true,
            "stock": {
                "managed": true,
                "is_in_stock": true,
                "qty": 45010
            }
        },
        {
            "sku": "TESTPRODUCT777",
            "sku_fulfiller": "TEST 777",
            "available": true,
            "stock": {
                "managed": true,
                "is_in_stock": true,
                "qty": 0
            }
        }
    ]
}
' "{{ENDPOINT}}v1/inventory"
PATCH %7B%7BENDPOINT%7D%7Dv1/inventory HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json

{
	"callback": {
        "url": "https://downloads.test.mypromo.com:10433/callback.php",
        "auth": {
            "oauth1": {
                "username": "user",
                "password": "pass",
                "auth_url": "https://myshop.com/api/auth"
            }
        }
    },
    "data": [
        {
            "sku": "TESTPRODUCT123",
            "sku_fulfiller": "TEST Prod-26",
            "available": true,
            "stock": {
                "managed": true,
                "is_in_stock": true,
                "qty": 14500
            }
        },
        {
            "sku": "TESTPRODUCT555",
            "sku_fulfiller": "TEST Prod-555",
            "available": true,
            "stock": {
                "managed": false,
                "is_in_stock": false,
                "qty": null
            }
        },
        {
            "sku": "TESTPRODUCT999",
            "sku_fulfiller": "TEST Prod 999",
            "available": true,
            "stock": {
                "managed": true,
                "is_in_stock": true,
                "qty": 45010
            }
        },
        {
            "sku": "TESTPRODUCT777",
            "sku_fulfiller": "TEST 777",
            "available": true,
            "stock": {
                "managed": true,
                "is_in_stock": true,
                "qty": 0
            }
        }
    ]
}
Example response
Status 400 Bad Request
{
    "message": "Invalid or missing property. 1 of 4 items have errors.",
    "errors": [
        {
            "sku": "TESTPRODUCT123",
            "sku_fulfiller": "TEST Prod-26",
            "error": "Invalid stock. Stock cant be negative."
        }
    ]
}
Status 200 OK
{
    "queue_id": 123,
    "message": "We received your request and notify you if a callback url was specified."
}

Patch inventory for merchants

Update availability in batches.

If you set your products to not available the product will still be available through the API but will not be synct to your mypromo shop or any other solution we offer connectors for as long it is available from the fulfiller or we have not deactivated the product for any other reason.

Requests are limited to 500 entries.

HTTP Request
PATCH {{ENDPOINT}}v1/inventory
Headers
Content-Type
application/json
Accept
application/json
PayLoad
{
    "callback": {
        "url": "https://downloads.test.mypromo.com:10433/callback.php",
        "auth": {
            "oauth2": {
                "username": "user",
                "password": "pass",
                "auth_url": "https://myshop.com/api/auth",
                "grant_type": "password_grant"
            }
        }
    },
    "data": [
        {
            "sku": "TESTPRODUCT123",
            "available": true
        },
        {
            "sku": "TESTPRODUCT555",
            "available": true
        },
        {
            "sku": "TESTPRODUCT999",
            "available": false
        },
        {
            "sku": "TESTPRODUCT777",
            "available": false
        }
    ]
}
Example request
curl -X PATCH -H "Content-Type: application/json" -H "Accept: application/json" -d '{
	"callback": {
        "url": "https://downloads.test.mypromo.com:10433/callback.php",
        "auth": {
            "oauth2": {
                "username": "user",
                "password": "pass",
                "auth_url": "https://myshop.com/api/auth",
                "grant_type": "password_grant"
            }
        }
    },
    "data": [
        {
            "sku": "TESTPRODUCT123",
            "available": true
        },
        {
            "sku": "TESTPRODUCT555",
            "available": true
        },
        {
            "sku": "TESTPRODUCT999",
            "available": false
        },
        {
            "sku": "TESTPRODUCT777",
            "available": false
        }
    ]
}
' "{{ENDPOINT}}v1/inventory"
PATCH %7B%7BENDPOINT%7D%7Dv1/inventory HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json

{
	"callback": {
        "url": "https://downloads.test.mypromo.com:10433/callback.php",
        "auth": {
            "oauth2": {
                "username": "user",
                "password": "pass",
                "auth_url": "https://myshop.com/api/auth",
                "grant_type": "password_grant"
            }
        }
    },
    "data": [
        {
            "sku": "TESTPRODUCT123",
            "available": true
        },
        {
            "sku": "TESTPRODUCT555",
            "available": true
        },
        {
            "sku": "TESTPRODUCT999",
            "available": false
        },
        {
            "sku": "TESTPRODUCT777",
            "available": false
        }
    ]
}
Example response
Status 200 OK
{
    "queue_id": 123,
    "message": "We received your request and notify you if a callback url was specified."
}
Status 400 Bad Request
{
    "message": "Invalid or missing property. 1 of 4 items have errors.",
    "errors": [
        {
            "sku": "TESTPRODUCT123",
            "sku_fulfiller": "TEST Prod-26",
            "error": "Invalid stock. Stock cant be negative."
        }
    ]
}

Get prices for fulfillers

Get a paged list of all products and their prices.

Optional filters:

  • from (int, default=0)
  • per_page (int, default=5)
  • sku OR sku_fulfiller (string)
HTTP Request
GET {{ENDPOINT}}v1/prices?from=0&per_page=250&sku=MP1234567890&sku_fulfiller=999999999&pagination=false
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/prices?from=0&per_page=250&sku=MP1234567890&sku_fulfiller=999999999&pagination=false"
GET %7B%7BENDPOINT%7D%7Dv1/prices?from=0&per_page=250&sku=MP1234567890&sku_fulfiller=999999999&pagination=false HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 200 OK
{
    "data": [
        {
            "sku": "TESTPRODUCT123",
            "sku_fulfiller": "TEST Prod-123",
            "rules": {
                "order_min_qty": 50,
                "order_max_qty": 200,
                "tier_price_qty_only": false
            },
            "prices": {
                "currency": "EUR",
                "purchase_prices": [
                    {
                        "qty": 50,
                        "price": 14.99
                    },
                    {
                        "qty": 100,
                        "price": 12.99
                    },
                    {
                        "qty": 200,
                        "price": 9.99
                    }
                ],
                "recommended_retail_prices": [
                    {
                        "qty": 50,
                        "price": 114.99
                    },
                    {
                        "qty": 100,
                        "price": 112.99
                    },
                    {
                        "qty": 200,
                        "price": 19.99
                    }
                ]
            }
        },
        {
            "sku": "TESTPRODUCT555",
            "sku_fulfiller": "TEST Prod-555",
            "rules": {
                "order_min_qty": 50,
                "order_max_qty": 10000,
                "tier_price_qty_only": true
            },
            "prices": {
                "currency": "EUR",
                "purchase_prices": [
                    {
                        "qty": 50,
                        "price": 14.99
                    },
                    {
                        "qty": 100,
                        "price": 12.99
                    },
                    {
                        "qty": 200,
                        "price": 9.99
                    }
                ],
                "recommended_retail_prices": [
                    {
                        "qty": 50,
                        "price": 114.99
                    },
                    {
                        "qty": 100,
                        "price": 112.99
                    },
                    {
                        "qty": 200,
                        "price": 19.99
                    }
                ]
            }
        }
    ],
    "links": {
        "first": "{{ENDPOINT}}v1/prices?page=1",
        "last": "{{ENDPOINT}}v1/prices?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "{{ENDPOINT}}v1/prices",
        "per_page": "5",
        "to": 1,
        "total": 3
    }
}

Get prices for merchants

Get a paged list of all products and their prices.

Optional filters:

  • from (int, default=0)
  • per_page (int, default=5)
  • sku (string)
  • shipping_from (iso2, default=DE)
HTTP Request
GET {{ENDPOINT}}v1/prices?from=0&per_page=250&sku=MP-F1-C0000003&shipping_from=DE&pagination=false
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/prices?from=0&per_page=250&sku=MP-F1-C0000003&shipping_from=DE&pagination=false"
GET %7B%7BENDPOINT%7D%7Dv1/prices?from=0&per_page=250&sku=MP-F1-C0000003&shipping_from=DE&pagination=false HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 200 OK
{
    "data": [
        {
            "sku": "TESTPRODUCT123",
            "rules": {
                "order_min_qty": 50,
                "order_max_qty": 200,
                "tier_price_qty_only": false
            },
            "prices": {
                "currency": "EUR",
                "buying_prices": [
                    {
                        "qty": 50,
                        "price": 14.99
                    },
                    {
                        "qty": 100,
                        "price": 12.99
                    },
                    {
                        "qty": 200,
                        "price": 9.99
                    }
                ],
                "recommended_retail_prices": [
                    {
                        "qty": 50,
                        "price": 114.99
                    },
                    {
                        "qty": 100,
                        "price": 112.99
                    },
                    {
                        "qty": 200,
                        "price": 19.99
                    }
                ],
                "sales_prices": [
                    {
                        "qty": 50,
                        "price": 100.99
                    },
                    {
                        "qty": 100,
                        "price": 100.99
                    },
                    {
                        "qty": 200,
                        "price": 14.99
                    }
                ]
            }
        },
        {
            "sku": "TESTPRODUCT555",
            "rules": {
                "order_min_qty": 50,
                "order_max_qty": 10000,
                "tier_price_qty_only": true
            },
            "prices": {
                "currency": "EUR",
                "buying_prices": [
                    {
                        "qty": 50,
                        "price": 14.99
                    },
                    {
                        "qty": 100,
                        "price": 12.99
                    },
                    {
                        "qty": 200,
                        "price": 9.99
                    }
                ],
                "recommended_retail_prices": [
                    {
                        "qty": 50,
                        "price": 114.99
                    },
                    {
                        "qty": 100,
                        "price": 112.99
                    },
                    {
                        "qty": 200,
                        "price": 19.99
                    }
                ],
                "sales_prices": [
                    {
                        "qty": 50,
                        "price": 100.99
                    },
                    {
                        "qty": 100,
                        "price": 100.99
                    },
                    {
                        "qty": 200,
                        "price": 14.99
                    }
                ]
            }
        }
    ],
    "links": {
        "first": "{{ENDPOINT}}v1/prices?page=1",
        "last": "{{ENDPOINT}}v1/prices?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "{{ENDPOINT}}v1/prices",
        "per_page": "5",
        "to": 1,
        "total": 3
    }
}

Patch prices for fulfillers

Update prices in batches.

Very important note:
All prices and quantities will be replaced with the given payload.
This has a direct impact to prices of merchants and availability for all merchants selling those products.
All not given quantities get lost. This is not recoverable. So be very carefully!

You can add new quantities and prices anytime again.

If you decide to offer your product from qty 1, just add a price for qty 1 with tier_price_qty_only=false and optional an upper limit from e.g. order_max_qty=1000. More samples: See payloads in this docs.

If you like to perform tests, please use our sandbox system or the dry run methods available in our web interface.

Price Rules:

  • order_min_qty is always lowest given qty and is set automatically
  • order_max_qty depends on tier_price_qty_only option: If false prices are understandable as from prices and you have to specify an order_max_qty value higher than the highest qty specified a price for (if not given we set a default of 200000). If false the the given qty can be ordered only.

Requests are limited to 500 entries.

HTTP Request
PATCH {{ENDPOINT}}v1/prices
Headers
Content-Type
application/json
Accept
application/json
PayLoad
{
    "callback": {
        "url": "https://downloads.test.mypromo.com:10433/callback.php",
        "auth": {
            "basic": {
                "username": "user",
                "password": "pass"
            }
        }
    },
    "data": [
        {
            "sku": "TESTPRODUCT123",
            "sku_fulfiller": "TEST Prod-123",
            "rules": {
                "order_max_qty": 1000,
                "tier_price_qty_only": false
            },
            "prices": {
                "currency": "EUR",
                "buying_prices": [
                    {
                        "qty": 50,
                        "price": 14.99
                    },
                    {
                        "qty": 100,
                        "price": 12.99
                    },
                    {
                        "qty": 200,
                        "price": 9.99
                    }
                ],
                "recommended_retail_prices": [
                    {
                        "qty": 50,
                        "price": 114.99
                    },
                    {
                        "qty": 100,
                        "price": 112.99
                    },
                    {
                        "qty": 200,
                        "price": 19.99
                    }
                ]
            }
        },
        {
            "sku": "TESTPRODUCT555",
            "sku_fulfiller": "TEST Prod 555",
            "rules": {
                "tier_price_qty_only": true
            },
            "prices": {
                "currency": "EUR",
                "buying_prices": [
                    {
                        "qty": 50,
                        "price": 14.99
                    },
                    {
                        "qty": 100,
                        "price": 12.99
                    },
                    {
                        "qty": 200,
                        "price": 9.99
                    }
                ],
                "recommended_retail_prices": [
                    {
                        "qty": 50,
                        "price": 114.99
                    },
                    {
                        "qty": 100,
                        "price": 112.99
                    },
                    {
                        "qty": 200,
                        "price": 19.99
                    }
                ]
            }
        }
    ]
}
Example request
curl -X PATCH -H "Content-Type: application/json" -H "Accept: application/json" -d '{
	"callback": {
        "url": "https://downloads.test.mypromo.com:10433/callback.php",
        "auth": {
            "basic": {
                "username": "user",
                "password": "pass"
            }
        }
    },
    "data": [
        {
            "sku": "TESTPRODUCT123",
            "sku_fulfiller": "TEST Prod-123",
            "rules": {
                "order_max_qty": 1000,
                "tier_price_qty_only": false
            },
            "prices": {
                "currency": "EUR",
                "buying_prices": [
                    {
                        "qty": 50,
                        "price": 14.99
                    },
                    {
                        "qty": 100,
                        "price": 12.99
                    },
                    {
                        "qty": 200,
                        "price": 9.99
                    }
                ],
                "recommended_retail_prices": [
                    {
                        "qty": 50,
                        "price": 114.99
                    },
                    {
                        "qty": 100,
                        "price": 112.99
                    },
                    {
                        "qty": 200,
                        "price": 19.99
                    }
                ]
            }
        },
        {
            "sku": "TESTPRODUCT555",
            "sku_fulfiller": "TEST Prod 555",
            "rules": {
                "tier_price_qty_only": true
            },
            "prices": {
                "currency": "EUR",
                "buying_prices": [
                    {
                        "qty": 50,
                        "price": 14.99
                    },
                    {
                        "qty": 100,
                        "price": 12.99
                    },
                    {
                        "qty": 200,
                        "price": 9.99
                    }
                ],
                "recommended_retail_prices": [
                    {
                        "qty": 50,
                        "price": 114.99
                    },
                    {
                        "qty": 100,
                        "price": 112.99
                    },
                    {
                        "qty": 200,
                        "price": 19.99
                    }
                ]
            }
        }
    ]
}
' "{{ENDPOINT}}v1/prices"
PATCH %7B%7BENDPOINT%7D%7Dv1/prices HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json

{
	"callback": {
        "url": "https://downloads.test.mypromo.com:10433/callback.php",
        "auth": {
            "basic": {
                "username": "user",
                "password": "pass"
            }
        }
    },
    "data": [
        {
            "sku": "TESTPRODUCT123",
            "sku_fulfiller": "TEST Prod-123",
            "rules": {
                "order_max_qty": 1000,
                "tier_price_qty_only": false
            },
            "prices": {
                "currency": "EUR",
                "buying_prices": [
                    {
                        "qty": 50,
                        "price": 14.99
                    },
                    {
                        "qty": 100,
                        "price": 12.99
                    },
                    {
                        "qty": 200,
                        "price": 9.99
                    }
                ],
                "recommended_retail_prices": [
                    {
                        "qty": 50,
                        "price": 114.99
                    },
                    {
                        "qty": 100,
                        "price": 112.99
                    },
                    {
                        "qty": 200,
                        "price": 19.99
                    }
                ]
            }
        },
        {
            "sku": "TESTPRODUCT555",
            "sku_fulfiller": "TEST Prod 555",
            "rules": {
                "tier_price_qty_only": true
            },
            "prices": {
                "currency": "EUR",
                "buying_prices": [
                    {
                        "qty": 50,
                        "price": 14.99
                    },
                    {
                        "qty": 100,
                        "price": 12.99
                    },
                    {
                        "qty": 200,
                        "price": 9.99
                    }
                ],
                "recommended_retail_prices": [
                    {
                        "qty": 50,
                        "price": 114.99
                    },
                    {
                        "qty": 100,
                        "price": 112.99
                    },
                    {
                        "qty": 200,
                        "price": 19.99
                    }
                ]
            }
        }
    ]
}
Example response
Status 200 OK
{
    "queue_id": 123,
    "message": "We received your request and notify you if a callback url was specified."
}
Status 400 Bad Request
{
    "message": "Invalid or missing property. 1 of 2 items have errors.",
    "errors": [
        {
            "sku": "TESTPRODUCT123",
            "sku_fulfiller": "TEST Prod-26",
            "error": "Invalid price. Not a float."
        }
    ]
}

Patch prices for merchants

Update prices in batches.

Important:
As a merchant you can see all prices but can update your sales price only.
Not specified quantities will not be updated.

Requests are limited to 500 entries.

HTTP Request
PATCH {{ENDPOINT}}v1/prices
Headers
Content-Type
application/json
Accept
application/json
PayLoad
{
    "callback": {
        "url": "https://downloads.test.mypromo.com:10433/callback.php",
        "auth": {
            "header": "Bearer: 1231313123"
        }
    },
    "data": [
        {
            "sku": "TESTPRODUCT123",
            "prices": {
                "currency": "EUR",
                "retail_prices": [
                    {
                        "qty": 50,
                        "price": 100.99
                    },
                    {
                        "qty": 100,
                        "price": 100.99
                    },
                    {
                        "qty": 200,
                        "price": 14.99
                    }
                ]
            }
        },
        {
            "sku": "TESTPRODUCT555",
            "prices": {
                "currency": "EUR",
                "retail_prices": [
                    {
                        "qty": 50,
                        "price": 100.99
                    },
                    {
                        "qty": 100,
                        "price": 100.99
                    },
                    {
                        "qty": 200,
                        "price": 14.99
                    }
                ]
            }
        }
    ]
}
Example request
curl -X PATCH -H "Content-Type: application/json" -H "Accept: application/json" -d '{
	"callback": {
        "url": "https://downloads.test.mypromo.com:10433/callback.php",
        "auth": {
            "header": "Bearer: 1231313123"
        }
    },
    "data": [
        {
            "sku": "TESTPRODUCT123",
            "prices": {
                "currency": "EUR",
                "retail_prices": [
                    {
                        "qty": 50,
                        "price": 100.99
                    },
                    {
                        "qty": 100,
                        "price": 100.99
                    },
                    {
                        "qty": 200,
                        "price": 14.99
                    }
                ]
            }
        },
        {
            "sku": "TESTPRODUCT555",
            "prices": {
                "currency": "EUR",
                "retail_prices": [
                    {
                        "qty": 50,
                        "price": 100.99
                    },
                    {
                        "qty": 100,
                        "price": 100.99
                    },
                    {
                        "qty": 200,
                        "price": 14.99
                    }
                ]
            }
        }
    ]
}
' "{{ENDPOINT}}v1/prices"
PATCH %7B%7BENDPOINT%7D%7Dv1/prices HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json

{
	"callback": {
        "url": "https://downloads.test.mypromo.com:10433/callback.php",
        "auth": {
            "header": "Bearer: 1231313123"
        }
    },
    "data": [
        {
            "sku": "TESTPRODUCT123",
            "prices": {
                "currency": "EUR",
                "retail_prices": [
                    {
                        "qty": 50,
                        "price": 100.99
                    },
                    {
                        "qty": 100,
                        "price": 100.99
                    },
                    {
                        "qty": 200,
                        "price": 14.99
                    }
                ]
            }
        },
        {
            "sku": "TESTPRODUCT555",
            "prices": {
                "currency": "EUR",
                "retail_prices": [
                    {
                        "qty": 50,
                        "price": 100.99
                    },
                    {
                        "qty": 100,
                        "price": 100.99
                    },
                    {
                        "qty": 200,
                        "price": 14.99
                    }
                ]
            }
        }
    ]
}
Example response
Status 400 Bad Request
{
    "message": "Invalid or missing property. 1 of 2 items have errors.",
    "errors": [
        {
            "sku": "TESTPRODUCT123",
            "sku_fulfiller": "TEST Prod-26",
            "error": "Invalid price. Not a float."
        }
    ]
}
Status 200 OK
{
    "queue_id": 123,
    "message": "We received your request and notify you if a callback url was specified."
}

Get SEO for merchants

Get a paged list of all products and their SEO relevant properties.

Optional filters:

  • from (int, default=0)
  • per_page (int, default=5)
  • sku (string)
HTTP Request
GET {{ENDPOINT}}v1/seo?from=0&per_page=250&sku=MP1234567890&pagination=false
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/seo?from=0&per_page=250&sku=MP1234567890&pagination=false"
GET %7B%7BENDPOINT%7D%7Dv1/seo?from=0&per_page=250&sku=MP1234567890&pagination=false HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 200 OK
{
    "data": [
        {
            "sku": "TESTPRODUCT-CUSTOMIZE",
            "defaults": {
                "product_name": "test name customize",
                "product_description": "test description customize",
                "product_description_short": "test description short",
                "product_description_secondary": "test description secondary",
                "meta_title": "test meta title",
                "meta_keywords": "test, meta, keywords",
                "meta_description": "test meta description"
            },
            "overwrites": {
                "product_name": "test name stock",
                "product_description": "test description stock",
                "product_description_short": "test description short stock",
                "product_description_secondary": "test description secondary stock",
                "meta_title": null,
                "meta_keywords": null,
                "meta_description": null
            }
        }
    ],
    "links": {
        "first": "{{ENDPOINT}}v1/seo?page=1",
        "last": "{{ENDPOINT}}v1/seo?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "{{ENDPOINT}}v1/seo",
        "per_page": "5",
        "to": 1,
        "total": 3
    }
}

Patch SEO for merchants

Update SEO texts in batches.

Important:
As a merchant you can overwrite all default texts.
If you like to reset to default properties set overwrites:null. This will reset all SEO URLs as well!
Not specified SKUs will not be updated.

Requests are limited to 500 entries.

HTTP Request
PATCH {{ENDPOINT}}v1/seo
Headers
Content-Type
application/json
Accept
application/json
PayLoad
{
    "callback": {
        "url": "https://downloads.test.mypromo.com:10433/callback.php",
        "auth": {
            "oauth1": {
                "username": "user",
                "password": "pass",
                "auth_url": "https://myshop.com/api/auth"
            }
        }
    },
    "data": [
        {
            "sku": "TESTPRODUCT-CUSTOMIZE",
            "overwrites": {
                "product_name": "test name customize",
                "product_description": "test description customize",
                "product_description_short": "test description short",
                "product_description_secondary": "test description secondary",
                "meta_title": "test meta title",
                "meta_keywords": "test, meta, keywords",
                "meta_description": "test meta description"
            }
        },
        {
            "sku": "TESTPRODUCT-STOCK",
            "overwrites": {
                "product_name": "test name stock",
                "product_description": "test description stock",
                "product_description_short": "test description short stock",
                "product_description_secondary": "test description secondary stock",
                "meta_title": null,
                "meta_keywords": null,
                "meta_description": null
            }
        }
    ]
}
Example request
curl -X PATCH -H "Content-Type: application/json" -H "Accept: application/json" -d '{
    "callback": {
        "url": "https://downloads.test.mypromo.com:10433/callback.php",
        "auth": {
            "oauth1": {
                "username": "user",
                "password": "pass",
                "auth_url": "https://myshop.com/api/auth"
            }
        }
    },
    "data": [
        {
            "sku": "TESTPRODUCT-CUSTOMIZE",
            "overwrites": {
                "product_name": "test name customize",
                "product_description": "test description customize",
                "product_description_short": "test description short",
                "product_description_secondary": "test description secondary",
                "meta_title": "test meta title",
                "meta_keywords": "test, meta, keywords",
                "meta_description": "test meta description"
            }
        },
        {
            "sku": "TESTPRODUCT-STOCK",
            "overwrites": {
                "product_name": "test name stock",
                "product_description": "test description stock",
                "product_description_short": "test description short stock",
                "product_description_secondary": "test description secondary stock",
                "meta_title": null,
                "meta_keywords": null,
                "meta_description": null
            }
        }
    ]
}
' "{{ENDPOINT}}v1/seo"
PATCH %7B%7BENDPOINT%7D%7Dv1/seo HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json

{
    "callback": {
        "url": "https://downloads.test.mypromo.com:10433/callback.php",
        "auth": {
            "oauth1": {
                "username": "user",
                "password": "pass",
                "auth_url": "https://myshop.com/api/auth"
            }
        }
    },
    "data": [
        {
            "sku": "TESTPRODUCT-CUSTOMIZE",
            "overwrites": {
                "product_name": "test name customize",
                "product_description": "test description customize",
                "product_description_short": "test description short",
                "product_description_secondary": "test description secondary",
                "meta_title": "test meta title",
                "meta_keywords": "test, meta, keywords",
                "meta_description": "test meta description"
            }
        },
        {
            "sku": "TESTPRODUCT-STOCK",
            "overwrites": {
                "product_name": "test name stock",
                "product_description": "test description stock",
                "product_description_short": "test description short stock",
                "product_description_secondary": "test description secondary stock",
                "meta_title": null,
                "meta_keywords": null,
                "meta_description": null
            }
        }
    ]
}
Example response
Status 200 OK
{
    "queue_id": 123,
    "message": "We received your request and notify you if a callback url was specified."
}
Status 400 Bad Request
{
    "message": "Invalid or missing property. 1 of 2 items have errors.",
    "errors": [
        {
            "sku": "TESTPRODUCT123",
            "error": "No overwrites specified."
        }
    ]
}

Get job status

Get list of product patch jobs.

If you decide using the webhook or a route to your API in order to receive callbacks the payload we push to your endpoint looks like the response of this request.
Possible status: SUCCESSS | ERROR | CANCELED | PROCESSING | SCHEDULED.
Report contains details as a spread sheet and can be downloaded using your api credentials.

HTTP Request
GET {{ENDPOINT}}v1/jobs/?from=1&per_page=15&pagination=false
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/jobs/?from=1&per_page=15&pagination=false"
GET %7B%7BENDPOINT%7D%7Dv1/jobs/?from=1&per_page=15&pagination=false HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 404 Not Found
{
    "message": "Not found."
}
Status 200 OK
{
    "data": [
        {
            "job_id": 123,
            "added": "2019-08-20T22:59:59.000000Z",
            "processed": "2019-08-20T23:59:59.000000Z",
            "status": "ERROR",
            "message": "100 of 500 entries contain errors.",
            "report": "https://api.mypromo.com/v1/XHLRZETDF8J4"
        },
        {
            "job_id": 124,
            "added": "2019-08-22T22:59:59.000000Z",
            "processed": "2019-08-22T23:59:59.000000Z",
            "status": "SUCCESS",
            "message": null,
            "report": "https://api.mypromo.com/v1/XHLRZETDF8J6"
        }
    ],
    "links": {
        "first": "{{ENDPOINT}}v1/jobs?page=1",
        "last": "{{ENDPOINT}}v1/jobs?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "{{ENDPOINT}}v1/jobs",
        "per_page": "5",
        "to": 1,
        "total": 1
    }
}

Get job status by id

Get details of a specified product patch job.

HTTP Request
GET {{ENDPOINT}}v1/jobs/{{JOBID}}
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/jobs/{{JOBID}}"
GET %7B%7BENDPOINT%7D%7Dv1/jobs/%7B%7BJOBID%7D%7D HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 404 Not Found
{
    "message": "Not found."
}
Status 200 OK
{
    "job_id": 123,
    "added": "2019-08-20T22:59:59.000000Z",
    "processed": "2019-08-20T23:59:59.000000Z",
    "status": "ERROR",
    "message": "100 of 500 entries contain errors.",
    "report": "https://api.mypromo.com/v1/XHLRZETDF8J4"
}

Production

Get all production orders

Retrieve your production orders.

Note: All links to files are protected and can downloaded by setting your bearer for the request.

Optional filters:

  • from (int, default=0)
  • per_page (int, default=5, max. 15)
  • created_from (date)
  • created_to (date)
  • updated_from (date)
  • updated_to (date)
HTTP Request
GET {{ENDPOINT}}v1/production_orders?from=0&per_page=5&created_from=2020-03-13&created_to=2020-03-13&updated_from=2020-01-01&updated_to=2020-12-31&pagination=false
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/production_orders?from=0&per_page=5&created_from=2020-03-13&created_to=2020-03-13&updated_from=2020-01-01&updated_to=2020-12-31&pagination=false"
GET %7B%7BENDPOINT%7D%7Dv1/production_orders?from=0&per_page=5&created_from=2020-03-13&created_to=2020-03-13&updated_from=2020-01-01&updated_to=2020-12-31&pagination=false HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 200 OK
{
    "data": [
        {
            "id": 61,
            "order_id": 70,
            "reference": "1582218043",
            "reference2": null,
            "complaint": false,
            "express_production": false,
            "express_shipping": false,
            "shipping_earliest": "2020-02-25T23:59:59.000000Z",
            "shipping_latest": "2020-03-01T23:59:59.000000Z",
            "shipping_late": 0,
            "status": "FINISHED",
            "comment": null,
            "generic_label": true,
            "clients": [
                {
                    "id": "id",
                    "type": "merchant",
                    "name": "Merchant x",
                    "contract_id": "M008",
                    "created_at": "2020-02-25T23:59:59.000000Z",
                    "updated_at": "2020-02-25T23:59:59.000000Z"
                },
                {
                    "id": "id",
                    "type": "fulfiller",
                    "name": "Fulfiller x",
                    "contract_id": "F012",
                    "created_at": "2020-02-25T23:59:59.000000Z",
                    "updated_at": "2020-02-25T23:59:59.000000Z"
                }
            ],
            "custom_properties": [
                {
                    "key": "property1",
                    "value": "value1"
                },
                {
                    "key": "property2",
                    "value": "value2"
                },
                {
                    "key": "property3",
                    "value": "value3"
                }
            ],
            "shipper": {
                "id": 287,
                "reference": "a9e8849c-8924-4095-beab-32958201f026",
                "company": "Sample Company",
                "department": null,
                "firstname": "Sam",
                "lastname": "Sample",
                "street": "Sample Street 1",
                "care_of": "Street add",
                "zip": "12345",
                "city": "Sample Town",
                "state_code": "NW",
                "district": "District",
                "country_code": "DE",
                "phone": "+4991234567890",
                "fax": null,
                "mobile": null,
                "email": "sam@sample.com",
                "vat_id": null,
                "commercial_register_entry": "Test123"
            },
            "recipient": {
                "id": 288,
                "reference": "dddb6f9e-62b2-44ee-9fa5-85cad6dc85c9",
                "company": "Sample Company",
                "department": null,
                "firstname": "Sam",
                "lastname": "Sample",
                "street": "Sample Street 1",
                "care_of": "Street add",
                "zip": "12345",
                "city": "Sample Town",
                "state_code": "NW",
                "district": "District",
                "country_code": "DE",
                "phone": "+491234567890",
                "fax": null,
                "mobile": null,
                "email": "sam@sample.com",
                "vat_id": null,
                "commercial_register_entry": "Test321"
            },
            "export": {
                "id": 289,
                "reference": "1039ed07-58ca-412c-8ec0-8abd7b0fab82",
                "company": "Sample Company",
                "department": null,
                "firstname": "Sam",
                "lastname": "Sample",
                "street": "Sample Street 1",
                "care_of": "Street add",
                "zip": "12345",
                "city": "Sample Town",
                "state_code": "NW",
                "district": "District",
                "country_code": "DE",
                "phone": "+491234567890",
                "fax": null,
                "mobile": null,
                "email": "sam@sample.com",
                "vat_id": null,
                "commercial_register_entry": "Test321444",
                "iban": null,
                "bic_or_swift": null,
                "account_holder": null,
                "eori_number": null
            },
            "production_order_items": [
                {
                    "id": 61,
                    "order_item_id": 83,
                    "reference": "05cteg84w3ltqxdaumnyvdhlg74z4uel",
                    "quantity": 5,
                    "sku": "TESTPRODUCT123",
                    "sku_fulfiller": "abc123",
                    "name": "Testproduct 123",
                    "type": "DESIGNS",
                    "shipping_earliest": "2020-02-25T23:59:59.000000Z",
                    "shipping_latest": "2020-03-01T23:59:59.000000Z",
                    "shipping_late": false,
                    "status": "FINISHED",
                    "custom_properties": [
                        {
                            "key": "property",
                            "value": "value"
                        },
                        {
                            "key": "property",
                            "value": "value"
                        },
                        {
                            "key": "property",
                            "value": "value"
                        }
                    ],
                    "configuration": [
                        {
                            "key": "property",
                            "value": "value"
                        },
                        {
                            "key": "property",
                            "value": "value"
                        },
                        {
                            "key": "property",
                            "value": "value"
                        }
                    ],
                    "files": [
                        {
                            "id": 159,
                            "url": "https://dev.api.mypromo.com/v1/download/159/poi/61",
                            "type": null,
                            "status": "PREFLIGHT_FINISHED"
                        }
                    ],
                    "designs": [
                        {
                            "id": 19,
                            "editor_start_url": "https://pf-geiger.stage-00.aws.rissc.net/editor/05cteg84w3ltqxdaumnyvdhlg74z4uel/edit",
                            "preview_url": "https://dev.api.mypromo.com/v1/designs/19/preview",
                            "status": "PREFLIGHT_FINISHED"
                        }
                    ],
                    "customs": {
                        "description": "Printed matter, n.e.s.",
                        "number": "49119900",
                        "origin": "DE",
                        "currency": "EUR",
                        "amount": 10.5
                    }
                }
            ],
            "histories": [
                {
                    "id": 365,
                    "text": "Production-Order created.",
                    "created_at": "2020-02-20T17:04:02.000000Z"
                },
                {
                    "id": 366,
                    "text": "Production-Order is now pending.",
                    "created_at": "2020-02-20T17:04:02.000000Z"
                },
                {
                    "id": 367,
                    "text": "Mail notification for Production-Order #61 sent to fulfiller.dev@mypromo.com",
                    "created_at": "2020-02-20T17:04:02.000000Z"
                },
                {
                    "id": 368,
                    "text": "Production started.",
                    "created_at": "2020-02-20T17:04:02.000000Z"
                },
                {
                    "id": 369,
                    "text": "File 'CPO61.xml' successfully via SFTP transferred.",
                    "created_at": "2020-02-20T17:04:02.000000Z"
                },
                {
                    "id": 370,
                    "text": "File 'CPO61_deliverySlip_1.pdf' successfully via SFTP transferred.",
                    "created_at": "2020-02-20T17:04:02.000000Z"
                },
                {
                    "id": 371,
                    "text": "File 'CPO61_printfile_1.pdf' successfully via SFTP transferred.",
                    "created_at": "2020-02-20T17:04:02.000000Z"
                },
                {
                    "id": 372,
                    "text": "Files have been successfully via SFTP transferred.",
                    "created_at": "2020-02-20T17:09:03.000000Z"
                },
                {
                    "id": 375,
                    "text": "Production-Order finished.",
                    "created_at": "2020-02-24T12:06:03.000000Z"
                },
                {
                    "id": 376,
                    "text": "Mail notification for Production-Order #61 sent to fulfiller.dev@mypromo.com",
                    "created_at": "2020-02-24T12:06:03.000000Z"
                }
            ],
            "files": [
                {
                    "id": 157,
                    "url": "https://dev.api.mypromo.com/v1/download/157/p/61",
                    "type": "deliverySlip",
                    "carrier": null,
                    "tracking_code": null,
                    "status": "DOWNLOADED"
                },
                {
                    "id": 158,
                    "url": "https://dev.api.mypromo.com/v1/61/hfnvG7",
                    "type": "labelGeneric",
                    "carrier": null,
                    "tracking_code": null,
                    "status": "FORWARDING"
                },
                {
                    "id": 159,
                    "url": "https://dev.api.mypromo.com/v1/61/untmG9",
                    "type": "label",
                    "carrier": "dhl",
                    "tracking_code": "45648797852547",
                    "status": "DOWNLOADED"
                }
            ],
            "shipments": [
                {
                    "id": 27,
                    "carrier": "ups",
                    "carrier_name": "UPS",
                    "tracking_id": "1Z2398234892349",
                    "tracking_url": "http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z2398234892349",
                    "delivered": false,
                    "delivery_earliest": null,
                    "delivery_latest": null,
                    "delivery_late": false,
                    "delivered_date": null,
                    "height": 30,
                    "width": 45,
                    "depth": 20,
                    "weight": 1000,
                    "status": "SHIPPED",
                    "force": false,
                    "production_order_items": [
                        {
                            "id": 61,
                            "order_item_id": 83,
                            "reference": "d3904f00-d5ba-417d-b6f5-dcb1f91f5dd4",
                            "quantity": 3,
                            "sku": "TESTPRODUCT123"
                        }
                    ]
                },
                {
                    "id": 30,
                    "carrier": "ups",
                    "carrier_name": "UPS",
                    "tracking_id": "1Z2398234892349",
                    "tracking_url": "http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z2398234892349",
                    "delivered": false,
                    "delivery_earliest": null,
                    "delivery_latest": null,
                    "delivery_late": false,
                    "delivered_date": null,
                    "height": 30,
                    "width": 45,
                    "depth": 20,
                    "weight": 1000,
                    "status": "SHIPPED",
                    "force": false,
                    "production_order_items": [
                        {
                            "id": 61,
                            "order_item_id": 83,
                            "reference": "d3904f00-d5ba-417d-b6f5-dcb1f91f5dd4",
                            "quantity": 2,
                            "sku": "TESTPRODUCT123"
                        }
                    ]
                }
            ],
            "created_at": "2020-02-20T17:04:02.000000Z",
            "updated_at": "2020-02-24T12:06:03.000000Z"
        }
    ],
    "links": {
        "first": "{{ENDPOINT}}v1/production_orders?page=1",
        "last": "{{ENDPOINT}}v1/production_orders?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "{{ENDPOINT}}v1/production_orders",
        "per_page": "5",
        "to": 1,
        "total": 1
    }
}

Get production order by id

Retrieve a specific production order.

If you decide using the webhook or a route to your API in order to receive production orders the payload we push to your endpoint looks like the response of this request.
Please keep in mind a call will be made on every status change (usually for new production orders and when those have been shipped completely (finished)).

Note: Files / Downloads are not public. Please use your API credentials to download files.

HTTP Request
GET {{ENDPOINT}}v1/production_orders/{{PRODUCTIONORDERID}}
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/production_orders/{{PRODUCTIONORDERID}}"
GET %7B%7BENDPOINT%7D%7Dv1/production_orders/%7B%7BPRODUCTIONORDERID%7D%7D HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 200 OK
{
    "id": 61,
    "order_id": 70,
    "reference": "1582218043",
    "reference2": null,
    "complaint": false,
    "express_production": false,
    "express_shipping": false,
    "shipping_earliest": "2020-02-25T23:59:59.000000Z",
    "shipping_latest": "2020-03-01T23:59:59.000000Z",
    "shipping_late": 0,
    "status": "FINISHED",
    "comment": null,
    "generic_label": true,
    "clients": [
        {
            "id": "id",
            "type": "merchant",
            "name": "Merchant x",
            "contract_id": "M008",
            "created_at": "2020-02-25T23:59:59.000000Z",
            "updated_at": "2020-02-25T23:59:59.000000Z"
        },
        {
            "id": "id",
            "type": "fulfiller",
            "name": "Fulfiller x",
            "contract_id": "F012",
            "created_at": "2020-02-25T23:59:59.000000Z",
            "updated_at": "2020-02-25T23:59:59.000000Z"
        }
    ],
    "custom_properties": [
        {
            "key": "property1",
            "value": "value1"
        },
        {
            "key": "property2",
            "value": "value2"
        },
        {
            "key": "property3",
            "value": "value3"
        }
    ],
    "shipper": {
        "id": 287,
        "reference": "a9e8849c-8924-4095-beab-32958201f026",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+4991234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": null,
        "commercial_register_entry": "Test123"
    },
    "recipient": {
        "id": 288,
        "reference": "dddb6f9e-62b2-44ee-9fa5-85cad6dc85c9",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+491234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": null,
        "commercial_register_entry": "Test321"
    },
    "export": {
        "id": 289,
        "reference": "1039ed07-58ca-412c-8ec0-8abd7b0fab82",
        "company": "Sample Company",
        "department": null,
        "firstname": "Sam",
        "lastname": "Sample",
        "street": "Sample Street 1",
        "care_of": "Street add",
        "zip": "12345",
        "city": "Sample Town",
        "state_code": "NW",
        "district": "District",
        "country_code": "DE",
        "phone": "+491234567890",
        "fax": null,
        "mobile": null,
        "email": "sam@sample.com",
        "vat_id": null,
        "commercial_register_entry": "Test321444",
        "iban": null,
        "bic_or_swift": null,
        "account_holder": null,
        "eori_number": null
    },
    "production_order_items": [
        {
            "id": 61,
            "order_item_id": 83,
            "reference": "05cteg84w3ltqxdaumnyvdhlg74z4uel",
            "quantity": 5,
            "sku": "TESTPRODUCT123",
            "sku_fulfiller": "abc123",
            "name": "Testproduct 123",
            "type": "DESIGNS",
            "shipping_earliest": "2020-02-25T23:59:59.000000Z",
            "shipping_latest": "2020-03-01T23:59:59.000000Z",
            "shipping_late": false,
            "status": "FINISHED",
            "custom_properties": [
                {
                    "key": "property",
                    "value": "value"
                },
                {
                    "key": "property",
                    "value": "value"
                },
                {
                    "key": "property",
                    "value": "value"
                }
            ],
            "configuration": [
                {
                    "key": "property",
                    "value": "value"
                },
                {
                    "key": "property",
                    "value": "value"
                },
                {
                    "key": "property",
                    "value": "value"
                }
            ],
            "files": [
                {
                    "id": 159,
                    "url": "https://dev.api.mypromo.com/v1/download/159/poi/61",
                    "type": null,
                    "status": "PREFLIGHT_FINISHED"
                }
            ],
            "designs": [
                {
                    "id": 19,
                    "editor_start_url": "https://pf-geiger.stage-00.aws.rissc.net/editor/05cteg84w3ltqxdaumnyvdhlg74z4uel/edit",
                    "preview_url": "https://dev.api.mypromo.com/v1/designs/19/preview",
                    "status": "PREFLIGHT_FINISHED"
                }
            ],
            "customs": {
                "description": "Printed matter, n.e.s.",
                "number": "49119900",
                "origin": "DE",
                "currency": "EUR",
                "amount": 10.5
            }
        }
    ],
    "histories": [
        {
            "id": 365,
            "text": "Production-Order created.",
            "created_at": "2020-02-20T17:04:02.000000Z"
        },
        {
            "id": 366,
            "text": "Production-Order is now pending.",
            "created_at": "2020-02-20T17:04:02.000000Z"
        },
        {
            "id": 367,
            "text": "Mail notification for Production-Order #61 sent to fulfiller.dev@mypromo.com",
            "created_at": "2020-02-20T17:04:02.000000Z"
        },
        {
            "id": 368,
            "text": "Production started.",
            "created_at": "2020-02-20T17:04:02.000000Z"
        },
        {
            "id": 369,
            "text": "File 'CPO61.xml' successfully via SFTP transferred.",
            "created_at": "2020-02-20T17:04:02.000000Z"
        },
        {
            "id": 370,
            "text": "File 'CPO61_deliverySlip_1.pdf' successfully via SFTP transferred.",
            "created_at": "2020-02-20T17:04:02.000000Z"
        },
        {
            "id": 371,
            "text": "File 'CPO61_printfile_1.pdf' successfully via SFTP transferred.",
            "created_at": "2020-02-20T17:04:02.000000Z"
        },
        {
            "id": 372,
            "text": "Files have been successfully via SFTP transferred.",
            "created_at": "2020-02-20T17:09:03.000000Z"
        },
        {
            "id": 375,
            "text": "Production-Order finished.",
            "created_at": "2020-02-24T12:06:03.000000Z"
        },
        {
            "id": 376,
            "text": "Mail notification for Production-Order #61 sent to fulfiller.dev@mypromo.com",
            "created_at": "2020-02-24T12:06:03.000000Z"
        }
    ],
    "files": [
        {
            "id": 157,
            "url": "https://dev.api.mypromo.com/v1/download/157/p/61",
            "type": "deliverySlip",
            "carrier": null,
            "tracking_code": null,
            "status": "DOWNLOADED"
        },
        {
            "id": 159,
            "url": "https://dev.api.mypromo.com/v1/61/untmG9",
            "type": "label",
            "carrier": "dhl",
            "tracking_code": "45648797852547",
            "status": "DOWNLOADED"
        }
    ],
    "shipments": [
        {
            "id": 27,
            "carrier": "ups",
            "carrier_name": "UPS",
            "tracking_id": "1Z2398234892349",
            "tracking_url": "http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z2398234892349",
            "delivered": false,
            "delivery_earliest": null,
            "delivery_latest": null,
            "delivery_late": false,
            "delivered_date": null,
            "height": 30,
            "width": 45,
            "depth": 20,
            "weight": 1000,
            "status": "SHIPPED",
            "force": false,
            "production_order_items": [
                {
                    "id": 61,
                    "order_item_id": 83,
                    "reference": "d3904f00-d5ba-417d-b6f5-dcb1f91f5dd4",
                    "quantity": 3,
                    "sku": "TESTPRODUCT123"
                }
            ]
        },
        {
            "id": 30,
            "carrier": "ups",
            "carrier_name": "UPS",
            "tracking_id": "1Z2398234892349",
            "tracking_url": "http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z2398234892349",
            "delivered": false,
            "delivery_earliest": null,
            "delivery_latest": null,
            "delivery_late": false,
            "delivered_date": null,
            "height": 30,
            "width": 45,
            "depth": 20,
            "weight": 1000,
            "status": "SHIPPED",
            "force": false,
            "production_order_items": [
                {
                    "id": 61,
                    "order_item_id": 83,
                    "reference": "d3904f00-d5ba-417d-b6f5-dcb1f91f5dd4",
                    "quantity": 2,
                    "sku": "TESTPRODUCT123"
                }
            ]
        }
    ],
    "created_at": "2020-02-20T17:04:02.000000Z",
    "updated_at": "2020-02-24T12:06:03.000000Z"
}

Get generic label

Retrieve shipping label for a production order.

Notes:

  • This is available if production_order.generic_label=true
  • You can still use your own labels, but have to pay them yourselves if you do not use the provided ones…

Response: Protected link to a PDF file with details like carrier and tracking code you can use when calling route ‘add_shipment’ later.

HTTP Request
GET {{ENDPOINT}}v1/production_orders/{{PRODUCTIONORDERID}}/generic_label
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/production_orders/{{PRODUCTIONORDERID}}/generic_label"
GET %7B%7BENDPOINT%7D%7Dv1/production_orders/%7B%7BPRODUCTIONORDERID%7D%7D/generic_label HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 200 OK
{
    "id": 159,
    "url": "https://dev.api.mypromo.com/v1/61/untmG9",
    "type": "label",
    "carrier": "dhl",
    "tracking_code": "45648797852547",
    "status": "DOWNLOADED"
}

Add shipment

Create one or more shipments for an production order.

carrier and tracking_code are mandatory.
If no item is specified the system assumes the whole production order was dispatched with this shipment.

All additional packages you submit are handeled as re-shipped packages e.g. due to complains, lost packages etc.
In this case providing production_order_items with a quantity is mandatory.

In case shipping labels had been supplied we expect the same carrier and tracking id sent back.
Exception: The merchant did not supply carrier and/or tracking_id. Then we assign provided labels automatically.

You can only report self-created labels after you have used all of the delivered labels.
Please download labels earliest on day of dispatch (especially generic labels) - the date of download annouces package for pick up the same day with the carrier.

Use force=true if you like to exceed the ordered quantity or usage of delivered labels e.g in case of new shipments for handling complains or creating labels on your own.

HTTP Request
POST {{ENDPOINT}}v1/production_orders/{{PRODUCTIONORDERID}}/add_shipment
Headers
Content-Type
application/json
Accept
application/json
PayLoad
{
    "carrier": "UPS",
    "tracking_code": "1Z123891378124",
    "height": 30,
    "width": 45,
    "depth": 20,
    "weight": 1000,
    "production_order_items": [
        {
            "id": 72,
            "quantity": 5
        }
    ],
    "force": false
}
Example request
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -d '{
    "carrier": "UPS",
    "tracking_code": "1Z123891378124",
    "height": 30,
    "width": 45,
    "depth": 20,
    "weight": 1000,
    "production_order_items": [
        {
            "id": 72,
            "quantity": 5
        }
    ],
    "force": false
}' "{{ENDPOINT}}v1/production_orders/{{PRODUCTIONORDERID}}/add_shipment"
POST %7B%7BENDPOINT%7D%7Dv1/production_orders/%7B%7BPRODUCTIONORDERID%7D%7D/add_shipment HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json

{
    "carrier": "UPS",
    "tracking_code": "1Z123891378124",
    "height": 30,
    "width": 45,
    "depth": 20,
    "weight": 1000,
    "production_order_items": [
        {
            "id": 72,
            "quantity": 5
        }
    ],
    "force": false
}
Example response
Status 400 Bad Request
{
    "message": "Please use all supplied labels first before creating shipments with own carrier contracts."
}
Status 400 Bad Request
{
    "message": "Please download label before creating a shipment for it."
}
Status 400 Bad Request
{
    "message": "The given quantity for the item #61 must not be greater than the remaining quantity '5'."
}
Status 201 Created
{
    "id": 27,
    "carrier": "ups",
    "carrier_name": "UPS",
    "tracking_code": "1Z2398234892349",
    "tracking_url": "http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z2398234892349",
    "delivered": null,
    "delivery_earliest": null,
    "delivery_latest": null,
    "delivery_late": null,
    "delivered_date": null,
    "height": 30,
    "width": 45,
    "depth": 20,
    "weight": 1000,
    "status": "SHIPPED",
    "force": false,
    "production_order_items": [
        {
            "id": 61,
            "order_item_id": 83,
            "reference": "d3904f00-d5ba-417d-b6f5-dcb1f91f5dd4",
            "quantity": 3,
            "sku": "TESTPRODUCT123"
        }
    ]
}

Miscellaneous

Helpers and others.

Download a file

Files are not public. Please use same auth you use for API (oAuth 2.0 - Bearer Token).
Files are returned as binary streams.

HTTP Request
GET https://api.mypromo.com/v1/rpp5kw
Headers
None
PayLoad
None
Example request
curl -X GET "https://api.mypromo.com/v1/rpp5kw"
GET /v1/rpp5kw HTTP/1.1
Host: api.mypromo.com

Get countries

Get a paged list of all available countries and details.

Optional filters:

  • from (int, default=0)
  • per_page (int, default=5)
HTTP Request
GET {{ENDPOINT}}v1/countries?from=0&per_page=15&pagination=false
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/countries?from=0&per_page=15&pagination=false"
GET %7B%7BENDPOINT%7D%7Dv1/countries?from=0&per_page=15&pagination=false HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 200 OK
{
    "data": [
        {
            "id": 1,
            "name": "Afghanistan",
            "iso2": "AF",
            "iso3": "AFG",
            "state_mandatory": false
        },
        {
            "id": 2,
            "name": "Egypt",
            "iso2": "EG",
            "iso3": "EGY",
            "state_mandatory": false
        },
        {
            "id": 3,
            "name": "Åland",
            "iso2": "AX",
            "iso3": "ALA",
            "state_mandatory": false
        },
        {
            "id": 4,
            "name": "Albania",
            "iso2": "AL",
            "iso3": "ALB",
            "state_mandatory": false
        },
        {
            "id": 5,
            "name": "Algeria",
            "iso2": "DZ",
            "iso3": "DZA",
            "state_mandatory": false
        },
        {
            "id": 6,
            "name": "American Samoa",
            "iso2": "AS",
            "iso3": "ASM",
            "state_mandatory": false
        },
        {
            "id": 7,
            "name": "Virgin Islands, U.S.",
            "iso2": "VI",
            "iso3": "VIR",
            "state_mandatory": false
        },
        {
            "id": 8,
            "name": "Andorra",
            "iso2": "AD",
            "iso3": "AND",
            "state_mandatory": false
        },
        {
            "id": 9,
            "name": "Angola",
            "iso2": "AO",
            "iso3": "AGO",
            "state_mandatory": false
        },
        {
            "id": 10,
            "name": "Anguilla",
            "iso2": "AI",
            "iso3": "AIA",
            "state_mandatory": false
        },
        {
            "id": 11,
            "name": "Antarctica",
            "iso2": "AQ",
            "iso3": "ATA",
            "state_mandatory": false
        },
        {
            "id": 12,
            "name": "Antigua and Barbuda",
            "iso2": "AG",
            "iso3": "ATG",
            "state_mandatory": false
        },
        {
            "id": 13,
            "name": "Equatorial Guinea",
            "iso2": "GQ",
            "iso3": "GNQ",
            "state_mandatory": false
        },
        {
            "id": 14,
            "name": "Argentina",
            "iso2": "AR",
            "iso3": "ARG",
            "state_mandatory": false
        },
        {
            "id": 15,
            "name": "Armenia",
            "iso2": "AM",
            "iso3": "ARM",
            "state_mandatory": false
        }
    ],
    "links": {
        "first": "{{ENDPOINT}}v1/countries?page=1",
        "last": "{{ENDPOINT}}v1/countries?page=17",
        "prev": null,
        "next": "{{ENDPOINT}}v1/countries?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 17,
        "path": "{{ENDPOINT}}v1/countries",
        "per_page": 15,
        "to": 15,
        "total": 251
    }
}

Get country by id

Get details of a specified country.

HTTP Request
GET {{ENDPOINT}}v1/countries/{{COUNTRYID}}
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/countries/{{COUNTRYID}}"
GET %7B%7BENDPOINT%7D%7Dv1/countries/%7B%7BCOUNTRYID%7D%7D HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 0
{
    "id": 50,
    "name": "Germany",
    "iso2": "DE",
    "iso3": "DEU",
    "state_mandatory": false
}

Get states

Get a paged list of all available states and details.

Optional filters:

  • from (int, default=0)
  • per_page (int, default=5)
HTTP Request
GET {{ENDPOINT}}v1/states?from=0&per_page=15&pagination=false
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/states?from=0&per_page=15&pagination=false"
GET %7B%7BENDPOINT%7D%7Dv1/states?from=0&per_page=15&pagination=false HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 200 OK
{
    "data": [
        {
            "id": 1,
            "name": "North Rhine-Westphalia",
            "iso2": "NW",
            "iso3": "DE-NW",
            "country_id": 1
        },
        {
            "id": 2,
            "name": "Baden-Württemberg",
            "iso2": "BW",
            "iso3": "DE-BW",
            "country_id": 1
        },
        {
            "id": 3,
            "name": "Bavaria",
            "iso2": "BY",
            "iso3": "DE-BY",
            "country_id": 1
        },
        {
            "id": 4,
            "name": "Berlin",
            "iso2": "BE",
            "iso3": "DE-BE",
            "country_id": 1
        },
        {
            "id": 5,
            "name": "Brandenburg",
            "iso2": "BB",
            "iso3": "DE-BB",
            "country_id": 1
        },
        {
            "id": 6,
            "name": "Bremen",
            "iso2": "HB",
            "iso3": "DE-HB",
            "country_id": 1
        },
        {
            "id": 7,
            "name": "Hamburg",
            "iso2": "HH",
            "iso3": "DE-HH",
            "country_id": 1
        },
        {
            "id": 8,
            "name": "Hesse",
            "iso2": "HE",
            "iso3": "DE-HE",
            "country_id": 1
        },
        {
            "id": 9,
            "name": "Mecklenburg-Western Pomerania",
            "iso2": "MV",
            "iso3": "DE-MV",
            "country_id": 1
        },
        {
            "id": 10,
            "name": "Lower Saxony",
            "iso2": "NI",
            "iso3": "DE-NI",
            "country_id": 1
        },
        {
            "id": 11,
            "name": "Rhineland-Palatinate",
            "iso2": "RP",
            "iso3": "DE-RP",
            "country_id": 1
        },
        {
            "id": 12,
            "name": "Saarland",
            "iso2": "SL",
            "iso3": "DE-SL",
            "country_id": 1
        },
        {
            "id": 13,
            "name": "Saxony",
            "iso2": "SN",
            "iso3": "DE-SN",
            "country_id": 1
        },
        {
            "id": 14,
            "name": "Saxony-Anhalt",
            "iso2": "ST",
            "iso3": "DE-ST",
            "country_id": 1
        },
        {
            "id": 15,
            "name": "Schleswig-Holstein",
            "iso2": "SH",
            "iso3": "DE-SH",
            "country_id": 1
        }
    ],
    "links": {
        "first": "{{ENDPOINT}}v1/states?page=1",
        "last": "{{ENDPOINT}}v1/states?page=301",
        "prev": null,
        "next": "{{ENDPOINT}}v1/states?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 301,
        "path": "{{ENDPOINT}}v1/states",
        "per_page": "15",
        "to": 15,
        "total": 4502
    }
}

Get state by id

Get details of a specified state of a country.

HTTP Request
GET {{ENDPOINT}}v1/states/{{STATESID}}
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/states/{{STATESID}}"
GET %7B%7BENDPOINT%7D%7Dv1/states/%7B%7BSTATESID%7D%7D HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 0
{
    "id": 2,
    "name": "Baden-Württemberg",
    "iso2": "BW",
    "iso3": "BAW",
    "country_id": 50
}

Get carriers

Get a paged list of all available carriers and details.

Optional filters:

  • from (int, default=0)
  • per_page (int, default=5)
HTTP Request
GET {{ENDPOINT}}v1/carriers?from=0&per_page=15&pagination=false
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/carriers?from=0&per_page=15&pagination=false"
GET %7B%7BENDPOINT%7D%7Dv1/carriers?from=0&per_page=15&pagination=false HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 200 OK
{
    "data": [
        {
            "id": 1,
            "name": "Royal Mail",
            "key": "royal-mail",
            "type": "parcel",
            "available": false
        },
        {
            "id": 2,
            "name": "dp-warenpost",
            "key": "dp-warenpost",
            "type": "parcel",
            "available": false
        },
        {
            "id": 3,
            "name": "DPD UK",
            "key": "dpd-uk",
            "type": "parcel",
            "available": false
        },
        {
            "id": 4,
            "name": "FedEx",
            "key": "fedex",
            "type": "parcel",
            "available": true
        },
        {
            "id": 5,
            "name": "FedEx UK",
            "key": "fedex-uk",
            "type": "parcel",
            "available": false
        },
        {
            "id": 6,
            "name": "UPS",
            "key": "ups",
            "type": "parcel",
            "available": true
        },
        {
            "id": 8,
            "name": "DHL",
            "key": "dhl",
            "type": "parcel",
            "available": true
        },
        {
            "id": 9,
            "name": "GLS",
            "key": "gls",
            "type": "parcel",
            "available": true
        },
        {
            "id": 10,
            "name": "DPD",
            "key": "dpd",
            "type": "parcel",
            "available": true
        },
        {
            "id": 11,
            "name": "Hermes",
            "key": "hermes",
            "type": "parcel",
            "available": true
        },
        {
            "id": 12,
            "name": "TNT",
            "key": "tnt",
            "type": "parcel",
            "available": true
        },
        {
            "id": 13,
            "name": "USPS",
            "key": "usps",
            "type": "parcel",
            "available": false
        },
        {
            "id": 14,
            "name": "UK Mail",
            "key": "uk-mail",
            "type": "parcel",
            "available": false
        },
        {
            "id": 15,
            "name": "Freight",
            "key": "freight",
            "type": "freight",
            "available": true
        },
        {
            "id": 16,
            "name": "Kuehne + Nagel",
            "key": "kn",
            "type": "freight",
            "available": true
        }
    ],
    "links": {
        "first": "{{ENDPOINT}}v1/carriers?page=1",
        "last": "{{ENDPOINT}}v1/carriers?page=2",
        "prev": null,
        "next": "{{ENDPOINT}}v1/carriers?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 2,
        "path": "{{ENDPOINT}}v1/carriers",
        "per_page": "15",
        "to": 15,
        "total": 16
    }
}

Get carrier by id

Get details of a specified carrier.

HTTP Request
GET {{ENDPOINT}}v1/carriers/{{CARRIERID}}
Headers
Content-Type
application/json
Accept
application/json
PayLoad
None
Example request
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" "{{ENDPOINT}}v1/carriers/{{CARRIERID}}"
GET %7B%7BENDPOINT%7D%7Dv1/carriers/%7B%7BCARRIERID%7D%7D HTTP/1.1
Host: 
Content-Type: application/json
Accept: application/json
Example response
Status 0
{
    "id": 2,
    "name": "DHL",
    "key": "dhl",
    "type": "parcel",
    "available": true
}