Getting Started (EN)

Welcome! Here you will find examples and a detailed endpoint list that will let you integrate WoowUp with the systems you use.

Getting started

This is a REST-style API that uses JSON for serialization. To start using the API you will need:

  1.Log into WoowUp and get your Api Key from the Configuration/MyAccount section.   2.Read the API docs to understand what you can do.

Basics

• All request receive and return data in JSON format.

• Remember to include in the header Basic Authentication when calling any endpoint. Here you’ll find how to do it.

• To identify a customer use the field “service_uid”. Normally you will use the email or the ID (DNI, CPF, RUT, Passport) to identify the customer.

• Every time you are going to use service_uid as part of the URL, first you’ll need to encode it with base64 and then with url encode. You can read here a detailed explanation here.

• Valid date formats are: YYYY-mm-dd HH:mm:ss (default in UTC) or ISO8601 format including the timezone Ex: 2004-02-12T15:19:21+03:00

• Normally you’ll include al the Product Information (sku, title, category, stock, etc) within the Create purchase order endpoint. But if you prefer, there is a specific endpoint to synchronize products.

• Before send a purchase order, you need to create the customer if it doesn't exist. In the example you can see how this process works in the "import_from_csv.php" file.

• Please, pay attention to the messages of the responses of our API because we will tell you if something is wrong with your requests or the information you send.

Rate Limiting

The API limits the number of requests per account to ensure service stability. The default limit is 140 requests per minute.

The system divides time into 30-second segments and always evaluates two segments: the current one and the previous one. Requests from the current segment count at 100%, while requests from the previous segment are weighted based on elapsed time — the more time has passed, the less they count.

This creates a smooth transition between windows, avoiding the classic fixed-counter problem where a client can double the limit at the reset boundary.

weight     = 1 - (elapsed_seconds / segment_duration)                                                                                                                 
estimated  = (previous_requests × weight) + current_requests                                                                                                          
                                                                                                                                                                        
if estimated ≥ limit → HTTP 429 

Example: The previous segment ended with 60 requests and the current one has 25, at 15 seconds into the segment:

weight    = 1 - (15 / 30) = 0.5                                                                                                                                       
estimated = (60 × 0.5) + 25 = 55 → Allowed (< 70)

Response Headers

Every API response includes rate limiting headers so you can monitor your usage:

Header	Description	Example
x-rate-limit-limit	Maximum requests per window	70
x-rate-limit-remaining	Remaining requests in current window	45
x-rate-limit-reset	Unix timestamp when the window resets	1742121660

When the limit is exceeded, the API responds with HTTP 429 Too Many Requests and includes:

Header	Description	Example
Retry-After	Seconds to wait before retrying	18

Example Responses:

Normal Response

HTTP/1.1 200 OK x-rate-limit-limit: 70 x-rate-limit-remaining: 45 x-rate-limit-reset: 1742121660

Rate Limited Response

Best Practices

• Monitor headers: Check x-rate-limit-remaining on each response to track your usage before hitting the limit.

• Retry with backoff: When you receive a 429, wait the number of seconds indicated in the Retry-After header before retrying.

• Distribute requests: Spread your calls evenly over time instead of sending bursts.

• Use pagination efficiently: Use higher limit values (e.g., ?limit=100) to reduce the number of requests needed.

If you need a higher rate limit, please contact your account manager or our support team.

Authentication

In any call to the API you must sent the apikey in the query string as a parameter.

For example, if your apikey is 'abcdefghijklmnopqrstuvwxyz', you should do a request to

https://api.woowup.com/apiv3/users?apikey=abcdefghijklmnopqrstuvwxyz

Other method, and the recomended, is via Authentication Header, in every call you must send the header

Authorization: Basic abcdefghijklmnopqrstuvwxyz

Deleted accounts

Requests from deleted accounts receive 410 Gone with code account_deleted. Once an account has been deactivated, its API key is no longer valid and all requests will be rejected.

{
    "payload": [],
    "message": "gone: account deleted",
    "code": "account_deleted"
}

Pagination

When you are doing a search, we paginate the results. In all paginated endpoints the pagination's parameters are:

Parameter	Description	Default
limit	Items per page returned. Max: 100	25
page	Number of the page. First page is 0	0

Returned format

All endpoints return data in json format, with the Content-Type: application/json header. For a correct use you have to send in all the requests the header Accept: application/json.

How to encode 'service_uid'

When you are trying to find an user you could identificate this by his id or his service_uid (commonly is the email), when you use the service_uid you must encode this in Base64 en the result encode as url safe, for example if you need to do this in php:

<?php

$service_uid = '[e-mail]';
$encoded_uid = urlencode(base64_encode($service_uid));
$url = 'https://api.woowup.com/apiv3/users/'.$encoded_uid.'/exist';

Sample Code: How to start sending us your purchase orders

In the following link you will find a fully functional example in PHP that process a CSV file with orders and customers and use the API to send them to WoowUp: Download example

Support

Remember to contact us on [e-mail] for any questions, we will be happy to assist you.