The plentymarkets REST API expands the functionality of the plentymarkets CMS and allows access to resources, i.e. data records, via unique URI paths. To use the REST API, you need to run an HTTP request and analyse the result. The REST API uses JSON as the communication format combined with the default HTTP methods GET, PUT, POST and DELETE:
We want to enhance your workflow with our API. For that reason, we built a whole new internal annotation progress. At the moment, we deliver a file you can use with your preferred API software. You can checkout our REST-Documentation, based upon the Swagger-UI, here.
You either can download it or check out our GitHub repository.
plentymarkets REST API uses OAuth 2.0. Most REST API calls do not require any specific authentication. There are a few exceptions, as some calls are only permitted for logged in front end or in some cases back end users. Calls that require authentication are flagged in the documentation.
/rest/login
The API uses the "Bearer" authentication scheme to transmit the access token. To get the token for authentication, use the Login call. By executing this POST method with a valid body, it will return a JSON object with the necessary data.
POST /rest/login HTTP/1.1 HOST: https://myplentyshop.com Content-Type: application/json Accept: application/json { "username": "myUsername", "password": "myPassword", }
Enter the
Authorization
key together with the token as the value in the HTTP header:
Authorization: Bearer
TOKEN
The plentymarkets REST API supports a maximum amount of simultaneously active users (the default number is 3, but it is
dependent on your contract).
If you try to access the API with more than the maximum number of users, you will receive the following a response with a 429
status code
and the following content:
To prevent misuse of the REST API and ensure a system's performance and stability, access to the REST API of any given plentymarkets system is throttled. The following limits apply:
Function | Rate: Basic | Rate: Classic | Rate: Flex | Rate: Plus |
---|---|---|---|---|
Reading calls per user and minute | 80 | 200 | 240 | 280 |
Reading calls per system and day | 59,760 | 166,000 | 282,000 | 282,000 |
Writing calls per user and minute | 40 | 80 | 100 | 120 |
Writing calls per system and day | 17,280 | 48,000 | 72,000 | 72,000 |
In addition to these limits, specific routes may be fitted with an individual limit, only applying to this route. For these routes, the limit will be visible in the REST documentation here on the plentymarkets developers website. The route will be labeled with a "THROTTLING" badge, the exact limit can be seen in the "Errors" section of that call.
Bulk REST routes help you to work efficiently within the throttling limits when handling large amounts of data. Check out the tutorial on bulk routes to find out which bulk routes are currently available.
To give external clients the ability to adjust to these limits and react accordingly, we will send additional headers with each response to a REST call. These headers are prefixed with one of these three prefixes, telling you what specific limitation they are informing about:
Header-Prefix | Meaning |
---|---|
X-Plenty-Global-Long-Period
|
The information in this header field refers to the Long period limit |
X-Plenty-Global-Short-Period
|
The information in this header field refers to the Short period limit |
X-Plenty-Route
|
The information in this header field refers to the individual route limit |
Depending on what follows the prefix, the headers have the following meanings:
Header | Meaning |
---|---|
$PREFIX$-Limit
|
The maximum number of calls for this limit |
$PREFIX$-Decay
|
Seconds until the current period ends and number of calls gets reset |
$PREFIX$-Calls-Left
|
Number of calls left for this period |
In addition, the following headers will be sent to the client if one or more of these limits are exceeded:
Header | Meaning |
---|---|
Retry-After
|
Seconds until the current period is over and the call count is reset. Hence, the number of seconds the client must wait until making the next call. |
$PREFIX$-Calls-Reset
|
Timestamp denoting the point in time when the call count for the specific limit (specified by the prefix) is reset |
When using the plentymarkets REST API, versioning is optional. If no version is specified in the HTTP header, then the newest version of the API is used. Alternatively, you can enter the following line in the HTTP header and swap out the version:
Accept: application/x.plentymarkets.
v1+json
As a rule, a JSON document is returned when a REST resource of the HTTP method
GET
is called. This JSON document can be parsed to a JSON object.
If PUT, POST or DELETE methods are also available for the resource, it accepts the JSON document received via GET. In many
cases, this allows for a very efficient work flow based on the following principle:
For designated GET requests, you can use the request parameters
page
and
itemsPerPage
to limit your request to the specified values. Both parameters are optional. With
itemsPerPage
, the call returns the numbers of entries specified with this parameter. In case of a maximum limit for
itemsPerPage
, the limit is defined in the parameter definition. The
page
parameter returns the specified page. In the example below, the plugins 1 to 10 (if there are 10+ plugins) from the first page
of the plugin inbox will be returned in the response JSON:
/rest/plugins/search?page=1&itemsPerPage=10
Click on the REST dropdown list, to access the pages that provide information on all resources currently available. Listed are the possible HTTP methods, the required parameters and the server response for each resource.
The following language codes are used in the plentymarkets REST API.
Code | Description |
---|---|
bg | Bulgarian |
cn | Chinese |
cz | Czech |
da | Danish |
de | German |
en | English |
es | Spanish |
fr | French |
it | Italian |
nl | Dutch |
nn | Norwegian |
pl | Polish |
pt | Portuguese |
ro | Romanian |
ru | Russian |
se | Swedish |
sk | Slovak |
tr | Turkish |
vn | Vietnamese |
The following country IDs are used in the plentymarkets REST API.
Country | ISO 3166-1 | plentymarkets ID |
---|---|---|
Germany | DE | 1 |
Austria | AT | 2 |
Belgium | BE | 3 |
Switzerland | CH | 4 |
Cyprus | CY | 5 |
Czech Republic | CZ | 6 |
Denmark | DK | 7 |
Spain | ES | 8 |
Estonia | EE | 9 |
France | FR | 10 |
Finland | FI | 11 |
United Kingdom | GB | 12 |
Greece | GR | 13 |
Hungary | HU | 14 |
Italy | IT | 15 |
Ireland | IE | 16 |
Luxembourg | LU | 17 |
Latvia | LV | 18 |
Malta | MT | 19 |
Norway | NO | 20 |
Netherlands | NL | 21 |
Portugal | PT | 22 |
Poland | PL | 23 |
Sweden | SE | 24 |
Singapore | SG | 25 |
Slovakia | SK | 26 |
Slovenia | SI | 27 |
USA | US | 28 |
Australia | AU | 29 |
Canada | CA | 30 |
China | CN | 31 |
Japan | JP | 32 |
Lithuania | LT | 33 |
Liechtenstein | LI | 34 |
Monaco | MC | 35 |
Mexico | MX | 36 |
Canary Islands | IC | 37 |
India | IN | 38 |
Brazil | BR | 39 |
Russia | RU | 40 |
Romania | RO | 41 |
Ceuta | EA | 42 |
Melilla | EA | 43 |
Bulgaria | BG | 44 |
Kosovo | XZ | 45 |
Kyrgyzstan | KG | 46 |
Kazakhstan | KZ | 47 |
Belarus | BY | 48 |
Uzbekistan | UZ | 49 |
Morocco | MA | 50 |
Armenia | AM | 51 |
Albania | AL | 52 |
Egypt | EG | 53 |
Croatia | HR | 54 |
Maldives | MV | 55 |
Malaysia | MY | 56 |
Hong Kong | HK | 57 |
Yemen | YE | 58 |
Israel | IL | 59 |
Taiwan | TW | 60 |
Guadeloupe | GP | 61 |
Thailand | TH | 62 |
Turkey | TR | 63 |
Greek Islands | GR | 64 |
Balearic Islands | ES | 65 |
New Zealand | NZ | 66 |
Afghanistan | AF | 67 |
Aland Islands | AX | 68 |
Algeria | DZ | 69 |
American Samoa | AS | 70 |
Andorra | AD | 71 |
Angola | AO | 72 |
Anguilla | AI | 73 |
Antarctica | AQ | 74 |
Antigua and Barbuda | AG | 75 |
Argentina | AR | 76 |
Aruba | AW | 77 |
Azerbaijan | AZ | 78 |
The Bahamas | BS | 79 |
Bahrain | BH | 80 |
Bangladesh | BD | 81 |
Barbados | BB | 82 |
Belize | BZ | 83 |
Benin | BJ | 84 |
Bermuda | BM | 85 |
Bhutan | BT | 86 |
Bolivia | BO | 87 |
Bosnia and Herzegovina | BA | 88 |
Botswana | BW | 89 |
Bouvet Island | BV | 90 |
British Indian Ocean Territory | IO | 91 |
Brunei Darussalam | BN | 92 |
Burkina Faso | BF | 93 |
Burundi | BI | 94 |
Cambodia | KH | 95 |
Cameroon | CM | 96 |
Cape Verde | CV | 97 |
Cayman Islands | KY | 98 |
Central African Republic | CF | 99 |
Chad | TD | 100 |
Chile | CL | 101 |
Christmas Island | CX | 102 |
Cocos Islands/Keeling Islands | CC | 103 |
Columbia | CO | 104 |
Comoros | KM | 105 |
Congo | CG | 106 |
Democratic Republic of the Congo | CD | 107 |
Cook Islands | CK | 108 |
Costa Rica | CR | 109 |
Ivory coast | CI | 110 |
Cuba | CU | 112 |
Djibouti | DJ | 113 |
Dominica | DM | 114 |
Dominican Republic | DO | 115 |
Ecuador | EC | 116 |
El Salvador | SV | 117 |
Equatorial Guinea | GQ | 118 |
Eritrea | ER | 119 |
Ethiopia | ET | 120 |
Falkland Islands | FK | 121 |
Faroe Islands | FO | 122 |
Fiji | FJ | 123 |
French Guiana | GF | 124 |
French Polynesia | PF | 125 |
French Southern and Antarctic Lands | TF | 126 |
Gabon | GA | 127 |
Gambia | GM | 128 |
Georgia | GE | 129 |
Ghana | GH | 130 |
Gibraltar | GI | 131 |
Greenland | GL | 132 |
Grenada | GD | 133 |
Guam | GU | 134 |
Guatemala | GT | 135 |
Guernsey | GG | 136 |
Guinea | GN | 137 |
Guinea-Bissau | GW | 138 |
Guyana | GY | 139 |
Haiti | HT | 140 |
Heard Island and McDonald Islands | HM | 141 |
Vatican City | VA | 142 |
Honduras | HN | 143 |
Iceland | IS | 144 |
Indonesia | ID | 145 |
Iran | IR | 146 |
Iraq | IQ | 147 |
Isle of Man | IM | 148 |
Jamaica | JM | 149 |
Jersey | JE | 150 |
Jordan | JO | 151 |
Kenya | KE | 152 |
Kiribati | KI | 153 |
Democratic People's Republic of Korea | KP | 154 |
Republic of Korea | KR | 155 |
Kuwait | KW | 156 |
Laos | LA | 158 |
Lebanon | LB | 159 |
Lesotho | LS | 160 |
Liberia | LR | 161 |
Libya | LY | 162 |
Macao | MO | 163 |
Macedonia | MK | 164 |
Madagascar | MG | 165 |
Malawi | MW | 166 |
Mali | ML | 168 |
Marshall Islands | MH | 169 |
Martinique | MQ | 170 |
Mauritania | MR | 171 |
Mauritius | MU | 172 |
Mayotte | YT | 173 |
Micronesia | FM | 174 |
Moldova | MD | 175 |
Mongolia | MN | 176 |
Montenegro | ME | 177 |
Montserrat | MS | 178 |
Mozambique | MZ | 179 |
Myanmar | MM | 180 |
Namibia | NA | 181 |
Nauru | NR | 182 |
Nepal | NP | 183 |
Netherlands Antilles | AN | 184 |
New Caledonia | NC | 185 |
Nicaragua | NI | 186 |
Niger | NE | 187 |
Nigeria | NG | 188 |
Niue | NU | 189 |
Norfolk Island | NF | 190 |
Northern Mariana Islands | MP | 191 |
Oman | OM | 192 |
Pakistan | PK | 193 |
Palau | PW | 194 |
Palestinian territories | PS | 195 |
Panama | PA | 196 |
Papua New Guinea | PG | 197 |
Paraguay | PY | 198 |
Peru | PE | 199 |
Philippines | PH | 200 |
Pitcairn Islands | PN | 201 |
Puerto Rico | PR | 202 |
Qatar | QA | 203 |
Reunion | RE | 204 |
Rwanda | RW | 205 |
Saint Helena | SH | 206 |
Saint Kitts and Nevis | KN | 207 |
Saint Lucia | LC | 208 |
Saint Pierre and Miquelon | PM | 209 |
Saint Vincent and the Grenadines | VC | 210 |
Samoa | WS | 211 |
San Marino | SM | 212 |
Sao Tome and Principe | ST | 213 |
Saudi Arabia | SA | 214 |
Senegal | SN | 215 |
Serbia | RS | 216 |
Seychelles | SC | 217 |
Sierra Leone | SL | 218 |
Solomon Islands | SB | 219 |
Somalia | SO | 220 |
South Africa | ZA | 221 |
South Georgia and the South Sandwich Islands | GS | 222 |
Sri Lanka | LK | 223 |
Sudan | SD | 224 |
Suriname | SR | 225 |
Spitsbergen and Jan Mayen | SJ | 226 |
Swaziland | SZ | 227 |
Syria | SY | 228 |
Tajikistan | TJ | 229 |
Tanzania | TZ | 230 |
Timor-Leste | TL | 231 |
Togo | TG | 232 |
Tokelau | TK | 233 |
Tonga | TO | 234 |
Trinidad and Tobago | TT | 235 |
Tunisia | TN | 236 |
Turkmenistan | TM | 237 |
Turks and Caicos Islands | TC | 238 |
Tuvalu | TV | 239 |
Uganda | UG | 240 |
Ukraine | UA | 241 |
United States Minor Outlying Islands | UM | 242 |
Uruguay | UY | 243 |
Vanuatu | VU | 244 |
Venezuela | VE | 245 |
Vietnam | VN | 246 |
British Virgin Islands | VG | 247 |
United States Virgin Islands | VI | 248 |
Wallis and Futuna | WF | 249 |
Western Sahara | EH | 250 |
Zambia | ZM | 252 |
Zimbabwe | ZW | 253 |
United Arab Emirates | AE | 254 |
Helgoland | DE | 255 |
Buesingen | DE | 256 |
Curaçao | CUW | 258 |
Sint Maarten | SXM | 259 |
BES Islands | BES | 260 |
Saint Barthélemy | BL | 261 |
Livigno | IT | 262 |
Campione d'Italia | IT | 263 |
Lake Lugano from Ponte Tresa to Porto Ceresio | IT | 264 |
Unknown | -- | 0 |
The following IDs are used for default units in the plentymarkets REST API.
Unit | ISO code | plentymarkets ID |
---|---|---|
Piece | C62 | 1 |
Kilogram | KGM | 2 |
Gram | GRM | 3 |
Milligram | MGM | 4 |
Litre | LTR | 5 |
12 pieces/dozen | DPC | 6 |
Two pack | OP | 7 |
Bale | BL | 8 |
Dispenser | DI | 9 |
Bag | BG | 10 |
Sheet | ST | 11 |
Block | D64 | 12 |
Block | PD | 13 |
Quire | QR | 14 |
Box | BX | 15 |
Coil | CL | 16 |
Container | CH | 17 |
Tin | TN | 18 |
Can | CA | 19 |
Dozen | DZN | 20 |
Bucket | BJ | 21 |
Case | CS | 22 |
Cask | Z3 | 23 |
Bottle | BO | 24 |
Fluid ounce | OZA | 25 |
Jar | JR | 26 |
Cardboard box | CG | 27 |
Carton | CT | 28 |
Kit | KT | 29 |
Ball | AA | 30 |
Metre | MTR | 31 |
Millilitre | MLT | 32 |
Millimetre | MMT | 33 |
Pair | PR | 34 |
Packet | PA | 35 |
Bundle | PK | 36 |
Pallet/unit load | D97 | 37 |
Square metre | MTK | 38 |
Square centimetre | CMK | 39 |
Square millimetre | MMK | 40 |
Square centimetre (non-standard) | SCM | 41 |
Square millimetre (non-standard) | SMM | 42 |
Role | RO | 43 |
Sack | SA | 44 |
Set | SET | 45 |
Reel | RL | 46 |
Each | EA | 47 |
Tube | TU | 48 |
Ounce | OZ | 49 |
Wet ton | WE | 50 |
Centimetre | CMT | 51 |
Inch | INH | 52 |
The plentymarkets REST API supports the following currencies. The currency ID is equivalent to the currency's ISO code.
ISO code | Currency |
---|---|
AED | United Arab Emirates dirham |
ARS | Argentine peso |
AUD | Australian dollar |
BGN | Bulgarian lev |
BHD | Bahraini dinar |
BRL | Brazilian real |
CAD | Canadian dollar |
CHF | Swiss franc |
CNY | Chinese Renminbi |
CZK | Czech koruna |
DKK | Danish krone |
EUR | Euro |
GBP | Pound sterling |
HKD | Hong Kong dollar |
HRK | Croatian kuna |
HUF | Hungarian forint |
IDR | Indonesian rupiah |
INR | Indian rupee |
JPY | Japanese yen |
MXN | Mexican peso |
MYR | Malaysian ringgit |
NOK | Norwegian krone |
NZD | New Zealand dollar |
PHP | Philippine peso |
PLN | Polish zloty |
QAR | Qatari riyal |
RON | Romanian leu |
RUB | Russian ruble |
SEK | Swedish krona |
SGD | Singapore dollar |
THB | Thai baht |
TRY | Turkish lira |
TWD | New Taiwan dollar |
UAH | Ukrainian hryvnia |
USD | United States dollar |
VND | Vietnamese dong |
XCD | Eastern Caribbean dollar |
ZAR | South African rand |
The following IDs are used for payment statuses in the plentymarkets REST API.
ID | Payment status |
---|---|
1 | Awaiting approval |
2 | Approved |
3 | Captured |
4 | Partially captured |
5 | Cancelled |
6 | Refused |
7 | Awaiting renewal |
8 | Expired |
9 | Refunded |
10 | Partially refunded |