Skip to main content

Mark order items as returned

PUT 
/financing/v1/applications/:applicationId/order/return

When some or all order items were returned by the customer to you (after delivery), use /financing/v1/applications/{applicationId}/order/return resource where {applicationId} is the application ID you received in the response of /financing/v1/applications after its creation.

If you want to cancel some items before marking those items as sent or delivered, use Mark order items as cancelled operation.

📘 For additional examples and more information, please refer to the Technical guide: Manage your orders.

Financing typeSupported
DEFERRED_PAYMENTYES
PAY_IN_THREEYES
Application stateAvailability
PROCESSINGNO
REJECTEDNO
CANCELLEDNO
READYYES

Use /financing/v1/applications/{applicationId}/order/return resource with an empty request to mark all order items (the whole order) as returned at once.

If you want to mark specific order item/s as returned, use /financing/v1/applications/{applicationId}/order/return resource with properly filled request that contains returned order items info. In this case request should contain array of returned order items with one or more particular order item identificators (code/EAN/name/type) - code, ean, name and type is used for identifying order item sent in Create application.

💡 TIP: Optionally, you can specify the amount (in the field totalPrice) that should be returned if it differs from the sum of the items' prices.

💡 TIP: Use an empty request if marking last (those not yet not marked) item(s) on order as returned.

⚠️ If multiple properties (code, ean, name or type) are used for identifying some order item, it all must exact match the item data.

If the request was successfully processed, you receive HTTP status code 200 and object of information about changed order plus basic information about respective application (ID, state, substate).

In other cases, you may receive errors similar to the following ones:

Status codeCodeExplanation
400INVALID_REQUESTRequest was not well formatted (malformed request syntax, size too large, etc.)
404OBJECT_NOT_FOUNDThe requested resource could not be found
422NOT_SUPPORTEDResource is not supported for given financing type

System notification. Some or all order items were returned by customer back to e-shop. Based on application financing type and partner setting, credit note may be issued.

Request​

Path Parameters

    applicationId stringrequired

    applicationId

Body

    items

    object[]

    List of changed items. All items are considered when empty.

  • Array [

    • code stringnullable

    Possible values: <= 200 characters

    Internal code for item (internal to e-shop). Used to better identify the item for future changes

    ean stringnullable

    Possible values: <= 64 characters

    EAN code.

    name stringnullable

    Possible values: <= 255 characters

    Item name

    type Item Typenullable

    Possible values: [PHYSICAL, DISCOUNT, SHIPPING_FEE, SALES_TAX, DIGITAL, GIFT_CARD, STORE_CREDIT, FEE, INSURANCE]

    Item type

    quantity numbernullable

    Possible values: >= 1

    (positive float/decimal up to 3 decimal places) Item quantity. If empty, considered as whole item quantity is selected

  • ]

    • totalPrice

    object

    The total financial amount of items (from the orderItems array). You can specify the amount if it differs from the sum of the item prices. If this amount is not specified, application.order.totalPrice is used.

    amount numberrequired

    Amount in minor units (12590 represents 125,90 CZK) ISO 4217

    currency stringrequired

    Amount currency. ISO 4217 (only CZK and EUR values are allowed)

    totalVat

    object[]

    Total VAT amounts of items (from orderItems array) split by their VAT rates.

  • Array [

    • amount numberrequired

    Amount in minor units (12590 represents 125,90 CZK) ISO 4217

    currency stringrequired

    Amount currency. ISO 4217 (only CZK and EUR values are allowed)

    vatRate numberrequired

    VAT rate as positive number (ie. 15 represents 15% rate). 0 is allowed.

  • ]

    • document

    object

    Attached document (e.g. invoice, credit note etc.)

    type Document Serializerrequired

    Possible values: [INVOICE, PROFORMA_INVOICE, CREDIT_NOTE, OTHER]

    Type of the document

    file

    object

    required

    oneOf

    string

    description stringnullable

    File description

    extraData

    object

    variableSymbol stringnullable

    Variable symbol of this document (proforma, invoice, ...). This string must contain only numbers, maximum length is 10 characters (digits). Leading zeros are ignored.

    variableSymbol string

    Possible values: <= 10 characters

    Variable symbol of the new document (credit note, ...). This symbols is used by Skip Pay to pair payment from e-shop. This string must contain only numbers, maximum length is 10 characters (digits). Leading zeros are ignored.

Responses​

Order items or whole order is marked as returned

Schema

    number stringrequired

    Possible values: <= 100 characters

    Order number (internal for e-shop)

    variableSymbols string[]

    Variable symbols for pairing. First symbol in array is used for making the payment to your account (if not specified later in Mark order items as sent or Mark order items as delivered) or we expect you make payment on our account with this symbol (if not specified later in Mark order items as returned operation). Strings must contain only numbers, maximum length is 10 characters (digits). Leading zeros are ignored.

    totalPrice

    object

    required

    Order total price including VAT.

    amount numberrequired

    Amount in minor units (12590 represents 125,90 CZK) ISO 4217

    currency stringrequired

    Amount currency. ISO 4217 (only CZK and EUR values are allowed)

    totalVat

    object[]

    required

    Total VAT amounts split by their VAT rates.

  • Array [

    • amount numberrequired

    Amount in minor units (12590 represents 125,90 CZK) ISO 4217

    currency stringrequired

    Amount currency. ISO 4217 (only CZK and EUR values are allowed)

    vatRate numberrequired

    VAT rate as positive number (ie. 15 represents 15% rate). 0 is allowed.

  • ]

    • addresses

    object[]

    Addresses. Only BILLING and DELIVERY types are allowed.

  • Array [

    • name stringnullable

    Possible values: <= 100 characters

    Name on address

    country stringrequired

    Country. (see ISO 3166 alpha-2)

    city stringrequired

    Possible values: <= 100 characters

    City

    streetAddress stringrequired

    Possible values: <= 100 characters

    Street/city part

    streetNumber stringnullable

    Possible values: <= 100 characters

    Street number

    zip stringrequired

    Possible values: <= 30 characters

    Postal code

    addressType addressTyperequired

    Possible values: [PERMANENT, CONTACT, DELIVERY, BILLING]

    Type of the address. Only some of the types are allowed in each context.

  • ]

    • deliveryType deliveryType

    Possible values: [DELIVERY_CARRIER, PERSONAL_BRANCH, PERSONAL_PARTNER, ONLINE]

    Delivery type, for DELIVERY_CARRIER type can be further specified by deliveryCarrier attribute.

    deliveryCarrier

    object

    oneOf

    carrierId carrierIdrequired

    Possible values: [AIRWAY, CZ_POST_HAND, CZ_POST_OFFICE, CZ_POST_OTHER, DACHSER, DB_SCHENKER, DEUTSCHE_POST_DHL, DHL, DHL_EXPRESS, DHL_FREIGHT, DPD, DSV, FEDEX, FOFR, GEBRUDER_WEISS, GEIS, GLS, HDS_COMFORT, HDS_STANDARD, IN_TIME, JAPO_TRANSPORT, LIFTAGO, LOCAL_COURIER, MAGYAR_POSTA, MALL_DELIVERY, MALL_DEPOSIT, MESSENGER, POSTA_BEZ_HRANIC, PPL, PPL_PARCEL_CONNECT, RABEN, SAMEDAY, SDS, SLOVAK_PARCEL_SERVICE, SLOVENSKA_POSTA, SPRING_GDS, TNT, TOP_TRANS, UPS, WEDO, WEDO_ULOZENKA, ZASILKOVNA]

    channel channel

    Possible values: [ESHOP, BRANCH, FRANCHISE, TELEPHONE, INTERNAL]

    Default value: ESHOP

    Sales channel, indicates how or where the order is created. (ie. via e-mail, eshop or at a branch)

    reservationDate datetimenullable

    Date and time until order is reserved.

    Until 'reservationDate' Skip Pay will try to notify partner with Application notification about approval or rejection.

    After this date and time, e-shop does not guarantee items availability (if application processing is longer, it may endanger order fullfillment).

    state Order Staterequired

    Possible values: [PROCESSING, SENT, DELIVERED, RETURNED, CANCELLED]

    Order state.

    deliveryDate datenullablerequired

    Date and time of delivery

    deliveryTrackingNumber stringnullablerequired

    Possible values: <= 64 characters

    Delivery tracking number

    sentDate datenullablerequired

    Date and time of order shipping

    documents

    object[]

    Attached documents (invoices etc.)

  • Array [

    • type Document Serializerrequired

    Possible values: [INVOICE, PROFORMA_INVOICE, CREDIT_NOTE, OTHER]

    Type of the document

    file

    object

    required

    filename stringrequired

    Possible values: <= 100 characters

    File name.

    url urlrequired

    File URL (URL is accessible only 1 hour from its generation for security reasons)

    description stringnullable

    File description

    extraData

    object

    variableSymbol stringnullable

    Variable symbol of this document (proforma, invoice, ...). This string must contain only numbers, maximum length is 10 characters (digits). Leading zeros are ignored.

  • ]

    • items

    object[]

    required

    Order items

  • Array [

    • code stringrequired

    Possible values: <= 200 characters

    Internal code for item (internal to e-shop). Used to better identify the item for future changes

    ean stringnullable

    Possible values: <= 64 characters

    EAN code.

    name stringrequired

    Possible values: <= 255 characters

    Item name

    type Item Typenullable

    Possible values: [PHYSICAL, DISCOUNT, SHIPPING_FEE, SALES_TAX, DIGITAL, GIFT_CARD, STORE_CREDIT, FEE, INSURANCE]

    Item type

    variant stringnullable

    Possible values: <= 250 characters

    Item variant

    description stringnullable
    producer stringnullable

    Possible values: <= 250 characters

    Producer name

    categories string[]nullable

    List of item categories

    totalPrice

    object

    required

    Order items total price including VAT.

    amount numberrequired

    Amount in minor units (12590 represents 125,90 CZK) ISO 4217

    currency stringrequired

    Amount currency. ISO 4217 (only CZK and EUR values are allowed)

    totalVat

    object

    required

    Order items VAT including VAT rate.

    amount numberrequired

    Amount in minor units (12590 represents 125,90 CZK) ISO 4217

    currency stringrequired

    Amount currency. ISO 4217 (only CZK and EUR values are allowed)

    vatRate numberrequired

    VAT rate as positive number (ie. 15 represents 15% rate). 0 is allowed.

    productUrl urlnullable

    Possible values: <= 200 characters

    URL of the item in e-shop

    state Order Staterequired

    Possible values: [PROCESSING, SENT, DELIVERED, RETURNED, CANCELLED]

    Order state.

    sentDate datenullablerequired

    Date when item was sent. Only when the whole order was NOT sent at once.

    deliveryDate datenullablerequired

    Date when item was delivered. Only when the whole order was NOT sent at once.

    deliveryTrackingNumber stringnullablerequired

    Possible values: <= 64 characters

    Tracking number for the item. Only when the whole order was NOT sent at once.

    image

    object

    filename stringrequired

    Possible values: <= 100 characters

    File name.

    url urlrequired

    File URL.

    unitPrice

    object

    required

    Order unit item price including VAT.

    amount numberrequired

    Amount in minor units (12590 represents 125,90 CZK) ISO 4217

    currency stringrequired

    Amount currency. ISO 4217 (only CZK and EUR values are allowed)

    unitVat

    object

    required

    Financial amount with VAT rate.

    amount numberrequired

    Amount in minor units (12590 represents 125,90 CZK) ISO 4217

    currency stringrequired

    Amount currency. ISO 4217 (only CZK and EUR values are allowed)

    vatRate numberrequired

    VAT rate as positive number (ie. 15 represents 15% rate). 0 is allowed.

    quantity numberrequired

    Possible values: >= 1

    (positive float/decimal up to 3 decimal places) Item quantity.

  • ]

    • merchantId stringnullablerequired

    Merchant identification

    applicationInfo

    object

    required

    Financing application base information

    id stringrequired

    Unique identifier in Skip Pay

    state staterequired

    Possible values: [PROCESSING, READY, REJECTED, CANCELLED]

    Application state.

    stateReason Reason Staterequired

    Possible values: [PROCESSING_REDIRECT_NEEDED, PROCESSING_PREAPPROVED, PROCESSING_VALIDATION_IN_PROGRESS, REJECTED, CANCELLED_NOT_PAID, READY_TO_SHIP, READY_SHIPPED, READY_DELIVERED, READY_PAID, CANCELLED_RETURNED]

    Describes internal state of application, e.g. when state is PROCESSING - reason why application remains in processing state

Loading...