Technical guide: Manage your orders

Welcome to our next guide! In our previous guide, you learned how to create a new application and went through the whole process step by step. In this guide, we will take the next step and show you how to manage your orders effectively.

Managing orders is essential for businesses that want to stay on top. In this guide, we will cover everything you need to know about managing your orders. We will show you how to get the details about your application, how to change the application order, and how to manage canceled or returned orders.

With this guide, you will be able to take full control of your orders and make the necessary changes to keep your business running smoothly. So let's dive into the world of order management with Skip Pay!

Before you start

Before you start, make sure you meet all the essential requirements below before you start creating a new application:

• Active Skip Pay registration for partners
• Skip Pay API credentials (user name, password and API key)
• Postman or software with similar functionality

Retrieve Application Details

In this step, we'll learn how to retrieve the details of an existing application. Once you've created an application using Skip Pay, you may need to access its details for various reasons, such as verifying its status or checking the customer's payment plan. To do so, we'll use the Get Application Detail API endpoint, which will provide us with all the relevant information about the application.

Good to know...

We proactively send updates to keep you informed of any changes. Stay connected with us by enabling notifications for timely information.

💡 More info about Application notification

1. Once your application is created, we can start to get the details about it. Open Postman and fill: GET https://api.partner.skippay.cz/financing/v1/applications/applicationId

Good to know...

You can find this endpoint in our API reference, along with additional information.

2. Fill in your applicationId that you got when you created the application in the Path.
3. Call the REST API. You will get all the details about your application such as state, stateReason, customer information, order information and much more.

Congratulations!

In this step, you have learned how to retrieve the details of your application. This information can be helpful for managing your orders and keeping track of your application's status. In the next step, we will cover how to change the order of your application.

Cancel Application

When it comes to online purchases, sometimes things don't go as planned. Perhaps customers changed their minds, circumstances have changed, or products will never be in stock , and you need to cancel your purchase. With SkipPay, we understand that things can happen, and we've made it easy for you to cancel your application. In this guide, we will walk you through the steps to cancel an application, so you can have peace of mind knowing that your online purchases are always under your control.

Warning!

Conditions for using the Cancel Application endpoint Please note that the Cancel Application endpoint is subject to certain conditions, including:

1. It is available for applications that are in a state of "processing."
2. It is also available for applications that are in a state of "ready," but only if the order associated with the application has not been marked as "sent" or "delivered" using the Mark Order Items as Sent or Mark Order Items as Delivered endpoints, respectively.
3. It is not available for applications that are in a state of "rejected" or "canceled."

If you have any questions or concerns about these conditions, please contact our support team for assistance.

1. If your application meets the conditions, we can start to cancel it. Open Postman and fill: PUT https://api.partner.skippay.cz/financing/v1/applications/applicationId/cancel

Good to know...

You can find this endpoint in our API reference, along with additional information.

2. Fill in your applicationId that you got when you created the application in the Path.
3. In the Body section, provide us with the reason why you want to cancel your applications. Your Body should look like this:

Cancel application Request example

{
  "reason": "APPLICATION_CANCELLED_BY_CUSTOMER"
}

4. Call the REST API. In response, you will get all available details about your cancellation.

Note that cancellation requests may not be accepted for every application. The state parameter will show the result of your request, including the following states:

State	State description
Processing	Application is being processed by Skip Pay
Ready	Application was approved and is ready for financing
Rejected	Application was rejected
Cancelled	Application was canceled by client, either before approval or after delivery

💡 More info about Application states

Good to know...

When the state is set to Processing, we provide a stateReason to indicate the current status and explain why the application remains in the processing state.

Change Application Order

In this step, we will cover how to change the order details of an existing application to accommodate these changes. Whether you need to change the financing amount, payment date, or other details, our API makes it easy to update your application as needed.

Warning!

Please note that if there are any changes within your order before delivery (such as a change in the order items that affects the total price of the order or other billing information), you can only make those changes if none of the items have been marked as sent or delivered. Once an order item has been marked as sent or delivered, it cannot be changed. Thank you for your understanding.

1. Once your application is created, we can start to change application order. Open Postman and fill: PUT https://api.partner.skippay.cz/financing/v1/applications/applicationId/order

Good to know...

You can find this endpoint in our API reference, along with additional information.

2. Fill in your applicationId that you got when you created the application in the Path.
3. In the Body section, provide us reason to change and update your application according to your needs. Your Body should look like this:

Change Application Order Request example

{
"reason": "There has been a change in the items on the order.", 
 "order": {
    "totalPrice": {
      "amount": 121000,
      "currency": "CZK"
    },
    "totalVat": [
      {
        "vatRate": 21,
        "amount": 21000,
        "currency": "CZK"
      }
    ],
    "items": [
      {
        "code": "EXC4677-1a",
        "name": "Tefal KO851830",
        "variant": "Digital Display Black",
        "producer": "Tefal",
        "categories": [
            "home electronic"
        ],
        "quantity": 1,
        "unitPrice": {
            "currency": "CZK",
            "amount": 121000
        },
        "totalPrice": {
            "currency": "CZK",
            "amount": 121000
        },
        "unitVat": {
            "vatRate": 21,
            "amount": 21000,
            "currency": "CZK"
        },
        "totalVat": {
            "vatRate": 21,
            "amount": 21000,
            "currency": "CZK"
        }
      }
    ]
  }
}

4. Call the REST API. In response, you will get all available details, including your changes.

Congratulations!

You have successfully learned how to change an application order using the Skip Pay API. Remember, you can make changes to your order at any time before it is marked as delivered. In the next step, we will show you how to manage canceled orders.

Manage Canceled Orders

In this section, we will cover how to manage canceled orders in Skip Pay. When an order is canceled, it needs to be properly handled to ensure that the order is marked as canceled in Skip Pay. We will walk you through the steps to retrieve details about the canceled order and process the refund. It's important to handle canceled orders promptly and efficiently to maintain customer satisfaction and avoid any potential issues.

We have basically two types of cancellations:

1. To cancel all order items (the whole order) at once, use the /financing/v1/applications/applicationId/order/cancel resource with an empty request.
2. To cancel specific order items, use the /financing/v1/applications/applicationId/order/cancel resource with a properly filled request that contains canceled order item information. In this case, the request should contain an array of canceled order items with one or more particular order item identifiers (code/EAN/name/type). The code, EAN, name, and type are used to identify the order item sent in "Create application."

Warning!

If multiple properties (code, EAN, name, or type) are used to identify an order item, all must match the item data exactly.

In our case, we are going to cancel a single application with one item:

1. Once your application is created, we can start to manage canceled orders. Open Postman and fill: PUT https://api.partner.skippay.cz/financing/v1/applications/aplicationId/order/cancel

Good to know...

You can find this endpoint in our API reference, along with additional information.

2. Fill in your applicationId that you got when you created the application in the Path.
3. In the Body section, update your items that you want to cancel according to your needs. Your Body should look like this:

Cancel single application with one item Request example

{
  "items": [
    {
      "code": "EXC4677-1a",
      "ean": "888462064002",
      "name": "iPhone 13 Pro Stříbrný",
      "type": "PHYSICAL",
      "quantity": 1
    }
  ],
  "totalPrice": {
    "amount": 19900,
    "currency": "CZK"
  },
  "totalVat": [
    {
      "amount": 19900,
      "currency": "CZK",
      "vatRate": 15
    }
  ]
}

4. Call the REST API. In response, you will get all available details including your changes.

Congratulations!

In this step, you have learned how to manage canceled orders in the Skip Pay API. Whether you want to cancel the whole order or just some specific items, the API provides the necessary resources for you to do so. By using these resources, you can easily manage your orders and keep your records up to date.

Manage Returned Orders

In this step, we will cover how to manage returned orders. If the customer decides to return some or all items from the order, you can use the Skip Pay API to manage this process. We will show you how to use this endpoint to manage the return of items and handle the necessary changes to the application order.

Warning!

Please note that returning funds to Skip Pay is required, not to the customer directly. Skip Pay will handle the necessary steps to process the refund for the customer.

We have basically two types of return management:

1. Mark all order items as returned: Use /financing/v1/applications/applicationId/order/return resource with an empty request to mark all order items (the whole order) as returned at once. Optionally, you can specify the amount (in the field totalPrice) that should be returned if it differs from the order's total price
2. Mark specific order item/s as returned: Use /financing/v1/applications/applicationId/order/returnreturn resource with properly filled request that contains returned order items info. In this case, the request should contain an array of returned order items with one or more particular order item identifiers (code/EAN/name/type) - code, EAN, name, and type are used for identifying order items sent in the Create application. Optionally, you can specify the amount (in the field totalPrice) that should be returned if it differs from the sum of the items' prices.

In our case, we are going to return a single application with one item:

1. Once your application is created, we can start to manage returned orders. Open Postman and fill: PUT https://api.partner.skippay.cz/financing/v1/applications/applicationId/order

Good to know...

You can find this endpoint in our API reference, along with additional information.

2. Fill in your applicationId that you got when you created the application in the Path.
3. In the Body section, update your items that you want to return according to your needs. You Body should look like this:

Return single application with one item Request example

{
  "items": [
    {
      "code": "EXC4677-1a",
      "ean": "888462064002",
      "name": "iPhone 13 Pro Stříbrný",
      "type": "PHYSICAL",
      "quantity": 1
    }
  ],
  "totalPrice": {
    "amount": 19900,
    "currency": "CZK"
  },
  "totalVat": [
    {
      "amount": 19900,
      "currency": "CZK",
      "vatRate": 15
    }
  ],
  "document": {
    "type": "INVOICE",
    "file": {
      "filename": "invoice.pdf",
      "content": "RmlsZSBjb250ZW50cy4gwq9cXyjjg4QpXy/Crw=="
    },
    "description": "This is an invoice",
    "extraData": {
      "variableSymbol": "1234567890"
    }
  },
  "variableSymbol": "1234567890"
}

4. Call the REST API. In response, you will get all available details including your changes.

Congratulations!

Thank you for completing the final step in managing your orders! We hope this guide has been helpful in teaching you how to manage returned orders. Remember that if you have any further questions or issues, our support team is always available to assist you.

Need help?

If you have any questions or issues related to managing your orders, send us an email at integrace@skippay.cz