Skip to content

Insert order ​

Insert a new order into the system. If the information is correct the order will be inserted as a cart and the files will be downloaded from the given urls. As soon as the download process is complete the cart will be converted into an order and the orderId will be assigned.

Endpoint ​

KeyValue
URLhttps://api.profotonet.nl/v1/order
MethodPOST

Request object for print(s) order ​

Key / Value overview ​

FieldTypeRequiredDefaultDescriptionNote
testBooleanfalsefalseIf test is true, the request is only tested on correctness.
testNotificationUrlStringfalsefalseIf test is true and testNotificationUrl is set, the test insert will also fire a status callback with test data. The status callback is explained in a different section of this documentation.
notificationUrlStringfalsefalseIf set, this url will be used for status callbacks for the order instead of the default notificationUrl filled in under your account.
referenceIdStringtrueYour unique id. This id is used to push and get the status and to reprint an order.
referenceStringfalseYour internal reference. This reference can be used if you need to contact customer support, if (for example) the referenceId is an UUID.
companyNameStringfalseCompanyname of the customer.
firstNameStringtrueFirstname of the customer.
lastNameStringtrueLastname of the customer.
emailAddressStringfalseEmail of the customer which will be used for send & track-notifications
phoneNumberStringfalsePhonenumber of the customer which will be used for send & track-notifications
streetStringtrueStreet of the customer.
houseNumberStringtrueHousenumber (+ addition) of the customer.
zipCodeStringtrueZipcode of the customer.
cityStringtrueCity of the customer.
stateStringfalseState of the customer.
countryStringtrueISO-3166 2 char country code
shippingMethodStringtruePossible values: pickup, send, postnlpickuppoint, sendaspackage (overwrites shippingmethod to package if it is going to be send as a letter).
pickupLocationCodeStringfalseRequired if shippingMethod is "postnlpickuppoint" and should contain the locationCode retrieved from the PostNL API. This value will be validated using the follow route: https://api.postnl.nl/shipment/v2_1/locations/lookup?LocationCode={pickupLocationCode}
sortingBooleanfalsefalseThis can be used to send in multiple orders in 1 batch after which the whole batch is sorted based on the sortingReference and thereafter will be shipped to 1 location. Additional charges will be applied. Sorting will only be applied to photoprints (lustre and glossy) to a maximum of 30x45 and photoproducts like keychains and mugs. Products like (for example) canvas, walldecoration and larger photo sizes are not prohibited within the order, but will not be individually sorted.
entriesArraytrueArray of all the entries.
entries[].referenceIdIntegertrue (false if productId starts with 12000)Your unique entry id. This id is used to reprint order.
entries[].productIdIntegertrueProductId supplied by us
entries[].quantityIntegertrueQuantity of the entry.
entries[].backprintStringfalseCustom backprint for the image (max 60 characters).
entries[].sortingReferenceStringfalseSortingReference (max. 60 characters) is required in combination with the sorting parameter. The sortingReference is used by us to know which parts of the orders need to be combined and the sortingReference will be visible behind the transparant window of the envelope. It is important to note that the sortingReferences need to be in consecutive order within entries (entries are basicly grouped together this way). Also Make sure that sortingReference is unique per order. An example of a sortingReference would be: "1A – Voornaam Achternaam - 100012".
entries[].fileObjecttrue (false if productId starts with 12000)Fileobject of the entry.
entries[].file.nameStringtrueOriginal filename including the extension (jpg, png, tiff or pdf if productId starts with 11000).
entries[].file.urlStringtrueUrl to download the file from.
entries[].file.md5StringfalseOptional MD5 of the file for extra checks after the download.
entries[].optionsArrayfalseOptions used for certain products.
entries[].options.codeStringtrueCode supplied by us to point to the option.
entries[].options.valueStringtrueAttribute values supplied by us for the option.
entries[].noteStringfalseOnly needed for products without a file (for example if a certain type of flyer needs to be added to the order). Note for the product (max 60 characters).
packingSlipObjectfalseCustom packingslip used to send with the order (pdf).
packingSlip.urlStringtrueUrl to download the packingslip from.
packingSlip.md5StringfalseOptional MD5 of the file for extra checks after the download.

Example of an order object ​

json
{
  test: true,
  testNotificationUrl: "https://testurl.ofyourwebsite.com/statuscallback",
  notificationUrl: "https://url.ofyourwebsite.com/statuscallback",
  referenceId: "10000000",
  reference: "10000000",
  companyName: "Company",
  firstName: "John",
  lastName: "Doe",
  emailAddress: "[email protected]",
  phoneNumber: "0031102912302",
  street: "Street",
  houseNumber: "1A",
  zipCode: "1234AA",
  city: "Rotterdam",
  state: "",
  country: "NL",
  shippingMethod: "send",
  entries: [
    {
      referenceId: 10000,
      productId: 1002201300190001,
      quantity: 1,
      backprint: "",
      file: {
        name: "testimage1.jpg",
        url: "https://images.testwebsite.nl/DH98sa7daKJhdKShdSD987/KJDShg9a8sd9878HDSAC.jpg",
        md5: "e2c0c4781074792afbaf73c6af5eae87"
      },
      options: [
        {
          code: "whiteborder",
          value: "checked"
        }
      ]
    },
    {
      referenceId: 10001,
      productId: 1003705000500003,
      quantity: 1,
      backprint: "",
      file: {
        name: "testimage2.png",
        url: "https://images.testwebsite.nl/DH98sa7daKJhdKShdSD987/KJDShg9a8sd9878HDSAD.png",
        md5: "7815696ecbf1c96e6894b779456d330e"
      },
      options: [
        {
          code: "canvasedge",
          value: "mirror"
        }
      ]
    }
  ],
  packingSlip: {
    url: "https://www.testwebsite.nl/DH98sa7daKJhdKShdSD987/KJDShg9a8sd9878HDSsada.pdf",
    md5: "6af0d8b2c5c3fff02066b31e8e83c192"
  }
}

Request object for photobook(s) order ​

Key / Value overview ​

FieldTypeRequiredDefaultDescription
testBooleanfalsefalseIf test is true, the request is only tested on correctness.
testNotificationUrlStringfalsefalseIf test is true and testNotificationUrl is set, the test insert will also fire a status callback with test data. The status callback is explained in a different section of this documentation.
notificationUrlStringfalsefalseIf set, this url will be used for status callbacks for the order instead of the default notificationUrl filled in under your account.
referenceIdStringtrueYour unique id. This id is used to push and get the status and to reprint an order.
referenceStringfalseYour internal reference. This reference can be used if you need to contact customer support, if (for example) the referenceId is an UUID.
companyNameStringfalseCompanyname of the customer.
firstNameStringtrueFirstname of the customer.
lastNameStringtrueLastname of the customer.
emailAddressStringfalseEmail of the customer which will be used for send & track-notifications
phoneNumberStringfalsePhonenumber of the customer which will be used for send & track-notifications
streetStringtrueStreet of the customer.
houseNumberStringtrueHousenumber (+ addition) of the customer.
zipCodeStringtrueZipcode of the customer.
cityStringtrueCity of the customer.
stateStringfalseState of the customer.
countryStringtrueISO-3166 2 char country code
shippingMethodStringtruePossible values: pickup, send, sendaspackage (overwrites shippingmethod to package if it is going to be send as a letter).
entriesArraytrueArray of all the entries.
entries[].referenceIdIntegertrue (false if productId starts with 12000)Your unique entry id. This id is used to reprint order.
entries[].productIdIntegertrueProductId supplied by us
entries[].quantityIntegertrueQuantity of the entry.
entries[].filesObjecttrue (false if productId starts with 12000)Filesobject of the entry.
entries[].files.coverEmbossingObjecttrue (if product contains embossing)If the photobook contains embossing this object is required. The coverFile is not needed in this case
entries[].files.coverEmbossing.line1StringtrueFirst line of embossing
entries[].files.coverEmbossing.line2Stringtrue (Depending on the PLU)Second line of embossing
entries[].files.coverEmbossing.line3Stringtrue (Depending on the PLU)Third line of embossing
entries[].files.coverFileObjecttrue (if product contains a photocover)If the photobook contains a photocover this object is required. The coverEmbossing is not needed in this case
entries[].files.coverFile.nameStringtrueOriginal filename including the extension (jpg, png, tiff or pdf if productId starts with 11000).
entries[].files.coverFile.urlStringtrueUrl to download the file from.
entries[].files.coverFile.md5StringfalseOptional MD5 of the file for extra checks after the download.
entries[].files.spreadFiles[]ArraytrueArray of all the spreadfiles for the photobook
entries[].files.spreadFiles[].nameStringtrueOriginal filename including the extension (jpg, png, tiff or pdf if productId starts with 11000).
entries[].files.spreadFiles[].urlStringtrueUrl to download the spread from.
entries[].files.spreadFiles[].md5StringfalseOptional MD5 of the file for extra checks after the download.

Example of an order object ​

json
{
  test: true,
  testNotificationUrl: "https://testurl.ofyourwebsite.com/statuscallback",
  notificationUrl: "https://url.ofyourwebsite.com/statuscallback",
  referenceId: "10000000",
  reference: "10000000",
  companyName: "Company",
  firstName: "John",
  lastName: "Doe",
  emailAddress: "[email protected]",
  phoneNumber: "031102912302",
  street: "Street",
  houseNumber: "1A",
  zipCode: "1234AA",
  city: "Rotterdam",
  state: "",
  country: "NL",
  shippingMethod: "pickup",
  entries: [
    {
        referenceId: "10000001",
        productId: "hardcoverbook_15x15_th-unthickened_pa-velvetalbum_co-embossingcover_cm-naturecork_em-1linelarge_ec-white",
        quantity: 1,
        files: {
            // If product contains a photocover
            coverFile: {
                name: "cover.jpg",
                url: "https://images.testwebsite.nl/7254230/cover.jpg",
                md5: "4680c4781074792afbaf73c6af5eakkj"
            },
            // If product contains embossing
            coverEmbossing: {
                line1: "Wedding in Italy",
                line2: "John & Gina",
                line3: "20-05-2026"
            },
            spreadFiles: [
                {
                    name: "spread_001.jpg",
                    url: "https://images.testwebsite.nl/7254230/spread_001.jpg",
                    md5: "2e70c4781074792afbaf73c6af5eanb6"
                },
                {
                    name: "spread_002.jpg",
                    url: "https://images.testwebsite.nl/7254230/spread_002.jpg",
                    md5: "ag40c4781074792afbaf73c6af5ea2df"
                },
                {
                    name: "spread_003.jpg",
                    url: "https://images.testwebsite.nl/7254230/spread_003.jpg",
                    md5: "c2e0c4781074792afbaf73c6af5eakj3"
                },
                {
                    name: "spread_004.jpg",
                    url: "https://images.testwebsite.nl/7254230/spread_004.jpg",
                    md5: "avg0c4781074792afbaf73c6af5ean99"
                },
                {
                    name: "spread_005.jpg",
                    url: "https://images.testwebsite.nl/7254230/spread_005.jpg",
                    md5: "98r0c4781074792afbaf73c6af5ea6yy"
                },
                {
                    name: "spread_006.jpg",
                    url: "https://images.testwebsite.nl/7254230/spread_006.jpg",
                    md5: "4tg0c4781074792afbaf73c6af5eallf"
                },
                {
                    name: "spread_007.jpg",
                    url: "https://images.testwebsite.nl/7254230/spread_007.jpg",
                    md5: "lk30c4781074792afbaf73c6af5eai90"
                },
                {
                    name: "spread_008.jpg",
                    url: "https://images.testwebsite.nl/7254230/spread_008.jpg",
                    md5: "2210c4781074792afbaf73c6af5ea7u8"
                },
                {
                    name: "spread_009.jpg",
                    url: "https://images.testwebsite.nl/7254230/spread_009.jpg",
                    md5: "5yh0c4781074792afbaf73c6af5ea33e"
                },
                {
                    name: "spread_010.jpg",
                    url: "https://images.testwebsite.nl/7254230/spread_010.jpg",
                    md5: "asd0c4781074792afbaf73c6af5eab21"
                },
                {
                    name: "spread_011.jpg",
                    url: "https://images.testwebsite.nl/7254230/spread_011.jpg",
                    md5: "lj60c4781074792afbaf73c6af5eae11"
                },
                {
                    name: "spread_012.jpg",
                    url: "https://images.testwebsite.nl/7254230/spread_012.jpg",
                    md5: "po90c4781074792afbaf73c6af5eae87"
                }
            ]
        }
    }
  ]
}

Response object(s) ​

Structure of the response messages.

Resultcodes ​

CodeDescription
200Success
400Bad request. Invalid parameters.
401Unauthorized. Check if APIid and APIkey are set correctly.
403Forbidden. Illegal action.
404Not found.
409Conflict. Already exists.
422Unprocessable entity. Incorrect parameters.
500Internal server error.

Response success ​

KeyValue
HTTP status code(s)200
TypeJSON

Examples will be added to the calls.

Success object ​

FieldTypeDescription
idObjectIdThe objectid assigned to the order.
statusStringThe status assigned to the order.
totalIntegerThe total of the order in cents (tax included). Returns 0 in test.
taxTotalIntegerThe total of the tax of the order in cents. Returns 0 in test.
subTotalIntegerThe subtotal of the order in cents (tax included). Returns 0 in test.
shippingTotalIntegerThe shippingtotal of the order in cents (tax included). Returns 0 in test.
shippingTaxTotalIntegerThe total of the tax of the shipping in cents. Returns 0 in test.
startingCostsTotalIntegerThe startingcoststotal of the order in cents (tax included). Returns 0 in test.
startingCostsTaxTotalIntegerThe total of the tax of the startingscosts in cents. Returns 0 in test.
entryTotals[].productIdIntegerProductId supplied by us.
entryTotals[].quantityIntegerTotal quantity of the cartentries ordered under the productId.
entryTotals[].totalIntegerTotal price of the cartentries ordered under the productId (tax included). Returns 0 in test.
entryTotals[].taxTotalIntegerTotal tax of the cartentries ordered under the productId. Returns 0 in test.
json
{
  id: "507f1f77bcf86cd799439011",
  status: "accepted"
  total: 8996,
  taxTotal: 1561,
  subTotal: 8322,
  shippingTotal: 575,
  shippingTaxTotal: 100,
  startingCostsTotal: 99,
  startingCostsTaxTotal: 17,
  entryTotals: [
      {
          productId: 1002201300190001,
          quantity: 1,
          total: 127,
          taxTotal: 22
      },
      {
          productId: 1003705000500003,
          quantity: 1,
          total: 8195,
          taxTotal: 1422
      }
  ]
}

Response error ​

KeyValue
HTTP status code(s)400, 401, 403, 404, 409, 422, 500
TypeJSON

Error object ​

FieldTypeDescription
errorsArrayAn array of the errors.
errors[].fieldStringThe field the error occurred on.
errors[].messageStringA description of the error.
json
{
  errors: [
    {
      field: "orderId",
      message: "Invalid parameter"
    }
  ]
}