creating test offers on allegro sandbox

[ahmed624]

Hello everyone,

I have a seller's account at allegro and I have registered and integrated my app with at the allegro sandbox and I am able to fetch application, user tokens.

now i want to create a couple of test orders at allegro sandbox so that i can test the downloading,dispatch, refund of orders through my app.

can you tell me how to post test orders on allegro? they say that i need to create some offers first to place order against. i have been trying to create offers through POSTMAN but it returns json parsing error. can someone send me a sample json to create a basic offer with a new product that is not in their database. and how can i then post orders against those offers to test the order APIs.

[AureliuszBrussy]

Please, see our guide in which we explain how to list an offer assigned to a product that is not in our database with one request. You can also check guides about listing an offer and assigning offers to a products.

To test your orders - create a new Sandbox account from which you will place orders.

You can also send here your request in curl format (with token removed) - I will check what is missing.

[ahmed624]

Thanks for the response Aureliusz,

so to test orders i need to create the offer first. (so that i can create orders using my buyer's account against the created offer) I am using the following JSON to create a dummy offer on my sandbox; endpoint: https://api.allegro.pl.allegrosandbox.pl/sale/product-offers request: { "product": { "name":"Produkt testowy", "category":{ "id":"258020" }, "parameters":[ { "id": "224017", "values": [ "test 1587459230" ] }, { "id": "202749", "values": [ "5.9" ] }, { "id": "202869", "values": [ "512 GB" ] }, { "id": "202829", "valuesIds": [ "202829_1" ] }, { "id": "202685", "valuesIds": [ "202685_212929" ] }, { "id": "127448", "valuesIds": [ "127448_2" ] }, { "id": "202865", "valuesIds": [ "202865_214109" ] }, { "id": "4388", "valuesIds": [ "4388_1" ] }, { "id": "202717", "values": [ 100 ] }, { "id": "219", "values": [ "Bluetooth" ] }, { "id": "202821", "values": [ "Dual SIM" ] } ] }, "sellingMode": { "price": { "amount": "220.85", "currency": "PLN" } }, "stock": { "available": 1 } }

and the response that i get is

{ "errors": [ { "code": "ShippingRatesNotFoundException", "message": "Unprocessable Entity", "details": null, "path": "delivery.shippingRates", "userMessage": "The user does not have a shipping rates named: default." } ] }

is there any default shipping rate setting at allegro thats i can use in this request? or how are couriers and shipping rates managed here?

[ahmed624]

and when i try to include any shipping id it gives the internal server error

Request:

{ "product": { "name":"Produkt testowy", "category":{ "id":"258020" }, "parameters":[ { "id": "224017", "values": [ "test 1587459230" ] }, { "id": "202749", "values": [ "5.9" ] }, { "id": "202869", "values": [ "512 GB" ] }, { "id": "202829", "valuesIds": [ "202829_1" ] }, { "id": "202685", "valuesIds": [ "202685_212929" ] }, { "id": "127448", "valuesIds": [ "127448_2" ] }, { "id": "202865", "valuesIds": [ "202865_214109" ] }, { "id": "4388", "valuesIds": [ "4388_1" ] }, { "id": "202717", "values": [ 100 ] }, { "id": "219", "values": [ "Bluetooth" ] }, { "id": "202821", "values": [ "Dual SIM" ] } ] }, "delivery": { "shippingRates": { "id": "862347c4-b2b0-42d4-b84a-1db01509a69d" } }, "sellingMode": { "price": { "amount": "220.85", "currency": "PLN" } }, "stock": { "available": 1 } }

Response:

{ "errors": [ { "code": "INTERNAL_SERVER_ERROR", "message": "Internal server error.", "details": null, "path": null, "userMessage": "Internal server error. Please try again in a few minutes." } ] }

[AureliuszBrussy]

First, you need to create shipping rates by using POST /sale/shipping-rates, and if you have a company account - you also need to create return policy (POST /after-sales-service-conditions/return-policies) and complaints policy (POST /after-sales-service-conditions/implied-warranties).

If the name of this offer terms will be "default" ("name": "default") - we are automatically using them in offer when you are using POST /sale/product-offers.

Also, your payload is missing images in product field, for example:

{
"product": {
"name":"Produkt testowy",
"images": [
        "https://...image-address.jpeg"
         ],
"category":{
        "id":"258020"
         }
...
    }
}

You can also create offer terms in the appropriate tab on the site.

Hint - if you want to get the correct structure of an offer to use POST /sale/offers resource, you can list offer via allegro.pl.allegrosandbox.pl and then download the offer using GET /sale/offers/{offerId}. Then, if you want to use payload from response to list an offer via POST /sale/offers - just remove id and publication.createdAt fields.

[AureliuszBrussy]

@ahmed624 it looks like you are using client_credentials flow to authorize. This is an authorization method without the user context. You should use another authorization method, for example code flow. All authorization methods are described in our guide.

[ahmed624]

Thanks for the prompt response Aureliusz,

We are using the device flow for auth instead of the code flow. because our application is running in a browser less environment.

The auth link is sent via email. Can you tell me the difference between code flow, device flow and client credentials and which to choose when ?

[AureliuszBrussy]

With Client_credentials flow authorization you will get access only to resources marked as “bearer-token-for-application” in the “Authorizations” section in documentation. You can use device flow on devices or in apps that do not have a graphic interface, a browser, or other simple mechanisms for entering the text.

Could you send us your full request and response in cURL format via our contact form? Please add GitHub thread number - #3731.

[ahmed624]

yes sure. For categories we are using client_credentials and for other resources like orders etc we use device auth. will share with you complete request on the form.

[ahmed624]

so first i created the return terms, then warranty information and then complaint terms. also created default delivery settings.

after that i sent the following POST dummy offer request to https://api.allegro.pl.allegrosandbox.pl/sale/product-offers

{ "product": { "name":"Produkt testowy", "category":{ "id":"258020" }, "images": [ "http://www.freepngimg.com/download/lion/3-2-lion-png.png", "http://www.freepngimg.com/download/lion/3-2-lion-png.png" ], "parameters":[ { "id": "224017", "values": [ "test 1587459230" ] }, { "id": "202749", "values": [ "5.9" ] }, { "id": "202869", "values": [ "512 GB" ] }, { "id": "202829", "valuesIds": [ "202829_1" ] }, { "id": "202685", "valuesIds": [ "202685_212929" ] }, { "id": "127448", "valuesIds": [ "127448_2" ] }, { "id": "202865", "valuesIds": [ "202865_214109" ] }, { "id": "4388", "valuesIds": [ "4388_1" ] }, { "id": "202717", "values": [ 100 ] }, { "id": "219", "values": [ "Bluetooth" ] }, { "id": "202821", "values": [ "Dual SIM" ] } ] }, "delivery": { "shippingRates": { "name": "default" } }, "sellingMode": { "price": { "amount": "220.85", "currency": "PLN" } }, "stock": { "available": 1 } }

the following response was received : { "errors": [ { "code": "INTERNAL_SERVER_ERROR", "message": "Internal server error.", "details": null, "path": null, "userMessage": "Internal server error. Please try again in a few minutes." } ] } also provided this information through the contact us form as you said. application number "11377616" ref:_00D24aE05._5003V7u0Wc:ref

[AureliuszBrussy]

Your request seems correct - the offer should be listed. Can you send me the trace-id of your request and the login of the account from which you are trying to list an offer?

[ahmed624]

well the login of our company seller account is VoloCommerce. I am using the sandbox.

can you please guide me how cal i tell the trace-id? I was using postman to list this offer.

[AureliuszBrussy]

Your account is not fully activated - you need to upload any two files in "Dane konta" tab ("choose file" button, then "wyślij do weryfikacji"). After that, listing the offer should be successful.

[ahmed624]

so you mean to say that to continue my testing i can attach any 2 dummy files for now in the after clicking the button shown in the screen below.

[AureliuszBrussy]

Yes, you just need to attach any two files by clicking "Choose File".

[ahmed624]

thanks AureliuszBrussy, I was able to list an offer at allegro thanks to you mate.

Now i want to create orders against this offer so that i can test my orders APIs integration with allegro. like downloads, dispatch refund etc.

Can you tell me how to create a test order against this offer that i created? FYI i have a buyers account as well as directed by your support earlier.

[AureliuszBrussy]

Just find your offer and place an order directly on the allegro.pl.allegrosandbox.pl website. You can simulate different variants of orders, refunds, etc.

[ahmed624]

and what parameter can be user to find the offer here? offer id?

[ahmed624]

okay so when i try to place an order it says i can not place an order on my own product.

when i try to logout and try to place the order it takes me to the login page.

and when i login with my buyer's account it says product not found.

please see screenshots of both scenarios.

is it because my seller account is on sandbox and buyers account is on live?

what do i need to do how to fix it?

[AureliuszBrussy]

You should try to search for this offer in a test environment, not in the production environment. Here's your offer.

[ahmed624]

so i need to create a buyer's account on sand box to place an order against this offer?

[AureliuszBrussy]

@ahmed624 yes, exactly. You need to create a buyer's account on Sandbox. Then search your offer on Sandbox and place an order.

[ahmed624]

Thanks Brussy will create another account and try to make orders using that, will let you know the results. it would be great if you include all these steps in your docs as well it helps really

[AureliuszBrussy]

Thank you for the suggestion. If you have some more questions - feel free to ask. I'll try to help.

[ahmed624]

yes Brussy I will continue to seek your guidance till our integration with Allegro APIs is complete. thank you so much for your support. We plan to integrate orders and products APIs so that our customers can use our allegro connector.

so, currently working on download orders, I was able place to orders on sandbox, then

1. downloaded events using order/events?limit=1000&type=READY_FOR_PROCESSING

2. then fetched order details for each event id using this order/checkout-forms/$checkoutform_id

3. then fulfilled the orders to set status to processing using this order/checkout-forms/" + order.getId() + "/fulfillment"

is this the correct sequence?

and one more thing why is it downloading the same order again n again? is there a way to stop downloading the order that has already been downloaded?

[AureliuszBrussy]

Yes, it is a correct sequence. Downloading an event does not mean its disappearance. We hold events for 60 days. You can download the newest events after a particular event, for example:

GET /order/events?limit=1000&from{last_seen_event_id}

You can sometimes retrieve several events of the same type (which apply to the same payment), in that situation you should check the order id in the checkoutForm object.

[ahmed624]

yes okay now moving to order delivery (shipment) my understanding is that

1. first change the fulfillment status to sent using PUT order/checkout-forms/{checkoutFormId}/fulfillment

2. then Add a parcel tracking number to the order using POST /order/checkout-forms/{id}/shipments

is this the correct order? and are there any other steps needed to be performed order delivery?

[AureliuszBrussy]

Yes, this is the correct order, but before you change the order fulfillment status (to the “PROCESSING”, “READY_FOR_SHIPMENT”, “SENT”) or you have not added a tracking number to the order, buyer may cancel the order within 3 days after purchase. When you changing the order fulfillment status via PUT /order/checkout-forms/{id}/fulfillment, use an optional parameter - checkoutForm.revision. You will be sure that you are changing the order fulfillment status (“fulfillment.status”), which exactly the same copy is in Allegro.

You can also check this guide where we describe how to handle situations like overpayment, underpayment, or payment refunds.

[ahmed624]

yes if you check my message sent yesterday this is the very reason that I change the status to PROCESSING as soon as i fetch the order.

[ahmed624]

okay so when i try to fulfill the order, I am getting foloowing response can you tell what it is?

I/O error on PUT request for "https://api.allegro.pl.allegrosandbox.pl/order/checkout-forms/9f89c2d1-07db-11eb-9f72-01d2d14a21e7/fulfillment": Unexpected end of file from server; nested exception is java.net.SocketException: Unexpected end of file from server

Data sent for this request was: data being sent to Allegro Service:{"status":"PROCESSING"}

[ahmed624]

can i have a reason for this error please?

[AureliuszBrussy]

I checked the logs and I can see that the order status has been changed to "PROCESSING". It seems that the error was returned by your application, not Allegro API.

[ahmed624]

ahan, can you please tell how can i confirm that the status has been changed or updated ?

[AureliuszBrussy]

You can check that by using GET /order/checkout-forms/{checkoutForm_id} resource. In response you will see the appropriate value in fulfillment.status field.

[ahmed624]

thanks Brussy, yes i was able to change the fulfillment status to processing . PFA

but the order status is still "ready for processing". PFA

when will the order status change? do i need to do myself? or will it be changed automatically when i change the fulfillment status to sent?

[ahmed624]

or do you think i dont need to worry about order status at all?

[AureliuszBrussy]

READY_FOR_PROCESSING status means that buyer filled in the shipping form, completed the payment (status “ended”), and selected COD or personal pickup, you can therefore proceed with the order. You cannot change this status (you can change only fulfillment.status).

There are other statuses, like BOUGHT, which means, that customer made the purchase but did not pay for the order. All possible statuses are listed in the guide.

[ahmed624]

okay now moving on to the order cancel and order refund functionality. my understanding is that we can not cancel orders using API only the customer can cancel it before we change the status to processing. for orders refund we can use https://api.allegro.pl/payments/refunds passing payment id and reason fields is mandatory and then for partial refunds we pass line items object (by quantity or by amount) but for full refund we pass delivery object (amount and currency) instead of line items. is my understanding correct?

[ahmed624]

and on making the refund request with the following data

data being sent to Allegro Service:{"payment":{"id":"1234567890"},"reason":"REFUND","lineItems":[],"delivery":{"value":{"amount":"0"}},"additionalServices":{"value":{"amount":"0"}}}

i received error code 422 with following message

Unprocessable Entity: [{"errors":[{"code":"VALIDATION_ERROR","message":"Invalid parameter format","details":"Invalid value: null","path":"delivery.value","userMessage":"Invalid parameter format"}]}]

can you please tell the reason ?

[ahmed624]

please respond so that I can move forward to the stock price updates

[AureliuszBrussy]

Order can be canceled only by the user. After that, you can mark orders as CANCELLED in fulfillment.status field.

As for refunding: in value structure, you need to also pass value the currency field:

"value": {
      "amount": "0",
      "currency": "PLN"
}

If you want to refund payment for all items in the order - you should provide all lineitem.id's. Do not forget about the possible refund of additional costs, such as delivery costs.

[ahmed624]

okay thanks Brussy after this i have tried to send update price request to the offer that i created earlier. following steps were performed: URI used was: https://api.allegro.pl.allegrosandbox.pl/sale/offer-price-change-commands/c6992ef6-4819-4357-a3ac-71907c6376c2

Request data: data being sent to Allegro Service:{"modification":{"type":"FIXED_PRICE","price":{"amount":"10","currency":"GBP"}},"offerCriteria":[{"offers":[{"id":"306c10d0-0c8e-11eb-bdbf-11335cc828c9"}],"type":"CONTAINS_OFFERS"}]}

response:

request HTTP Status Code: 400 BadRequest: 400 Bad request: [

400 Bad request

Your browser sent an invalid request.

[ahmed624]

can you please tell what I am doing wrong herE? thank you so much for your support any ways Brussy. I just have update stocks and update product request left after this one. and then we will beta release our allegro connector to our customers in the UK

[ahmed624]

can you please update Brussy as i am stuck on this request.

[AureliuszBrussy]

You are passing incorrect offer id (306c10d0-0c8e-11eb-bdbf-11335cc828c9). Offer id is shorter, for example: 7678634013. Also, at the moment you should only use "PLN" value in the currency field.

[ahmed624]

okay let me update this thing then will get back to you. thanks Brussy

[ahmed624]

okay so i tried again but its the same result. following is the detail Brussy;

URI: https://api.allegro.pl.allegrosandbox.pl/sale/offer-price-change-commands/bac9fd97-5982-4693-96a4-6f43391e7041 request data being sent to Allegro Service:{"modification":{"type":"FIXED_PRICE","price":{"amount":"0","currency":"PLN"}},"offerCriteria":[{"offers":[{"id":"7678669681"}],"type":"CONTAINS_OFFERS"}]} response: 400 Bad request: [

400 Bad request

Your browser sent an invalid request. now can you please tell why cant i change my offer price?

[AureliuszBrussy]

Could you send your full request in a curl format? There is one mistake in your payload - you cannot change the price to 0, but error 400 should not appear in this case.

[ahmed624]

Hi Brussy ye so the request looks like;

curl -X PUT \ https://api.allegro.pl.allegrosandbox/sale/offer-price-change-commands/bac9fd97-5982-4693-96a4-6f43391e7041 \ -H 'Authorization: Bearer {token}' \ -H 'Accept: application/vnd.allegro.public.v1+json' \ -H 'Content-Type: application/vnd.allegro.public.v1+json' \ -d '{ "modification":{ "type":"FIXED_PRICE", "price":{ "amount":"0", "currency":"PLN" } }, "offerCriteria":[ { "offers":[ { "id":"7678669681" } ], "type":"CONTAINS_OFFERS" } ] }'

[ahmed624]

also for offer creation I have a few questions to clear my understanding;

1) I observed that allegro assigns an offer_id and a product_id when we try to create a new offer. can we send our own product_id while creating offers? (sale/product-offers) so that we are able to create multiple variants of the same product? my understanding is that each variant has to be created as a separate offer using the same product id.

2) can we create offers in products created by other sellers? like products that already exist on the marketplace and we want to list our offers in them? if yes then whats the mechanism?

3) is allegro catalog based? like if we try to create a product that already exists will it give an error or accept it as a new product?

[ahmed624]

were you able to take a look brussy?