Delivery methods
How gifts reach recipients: EMAIL, TEXT, LINK, DIRECT_SHIPPING, and CODE — and what each requires.
The delivery.method you choose when creating an order determines how the gift reaches the recipient — and what information you must provide.
Choosing a method
| Method | How the gift is delivered | You must provide | Best for |
|---|---|---|---|
EMAIL | We email the voucher to the recipient | recipient.name, recipient.email, sender.name | Most digital gifting |
TEXT | We send the voucher via SMS | recipient.name, recipient.phone_number (in the product country's format), sender.name | Recipients you have phone numbers for |
LINK | You get a secure voucher URL and deliver it through your own channel (your app, chat, push, etc.) | recipient.name, sender.name | In-app rewards, full control over delivery UX |
DIRECT_SHIPPING | We ship a physical product to the address you provide | recipient.name, recipient.address, sender.name | Physical gifts when you already have the address |
CODE | No delivery at all — you receive the raw voucher code (value / PIN / URL) and use it however you like | Nothing (no recipient or sender needed) | Wallet top-ups, printing codes, custom fulfillment |
Every product supports a specific subset of methods — check available_delivery_method in the product catalog before ordering.
Send only the fields a method needs
Provide the fields listed above for your chosen method and omit the rest. Sending a field the method does not use is not supported, and may stop being accepted in a future release.
WithLINK, do not sendrecipient.email. You deliver the voucher link yourself, so SodaGift never uses the address. This combination is deprecated.
Phone number format
Korean and Japanese numbers are normalized before they are checked, so the country code and separators are optional. For a Korean product, all of these are accepted and stored as 01012345678:
01012345678 · 010-1234-5678 · 1012345678 · 821012345678 · +821012345678 · +82 10-1234-5678
The number must still be a valid Korean mobile number once normalized — 10 or 11 digits beginning with 01. Anything else, a landline for example, is rejected with invalid_phone_number_format.
For other countries, enter the number in the local format of the product's country.
Retrieving the voucher after ordering
For LINK and CODE, the order creation response does not contain the voucher itself. Fetch it with GET /v1/orders/{id}:
LINK→order_items[].delivery.link— a secure URL for the recipient.CODE→order_items[].delivery.code—{ value, pin, url, expired_at }. Which ofvalue/pin/urlare populated varies by product — some vouchers are a code string, some are a redemption URL, some are a combination. Each field can benull, so handle all combinations.
Treat links and codes as secrets. Anyone holding the URL or code can redeem the gift. Deliver them only to the intended recipient, and never log them.
Recipient-provided delivery information
Some products let the recipient enter their own delivery details (e.g. their shipping address) through a secure link, instead of you collecting them upfront. This is controlled by the product's recipient_info_provided_by field:
["SENDER"]— you provide all delivery details at order time.["RECIPIENT"]or["SENDER", "RECIPIENT"]— the recipient can be asked to fill in their own details. The secure link is sent viaEMAILorLINK(and via SMS forMERCHANDISEproducts ordered withTEXT).
In recipient-provided flows:
- The order item stays
PENDINGuntil the recipient submits their information ("accepts" the gift). Track this viaorder_items[].delivery.recipient.acceptance—{ status: PENDING | ACCEPTED | EXPIRED, expiry_date }. - If the acceptance link expires before the recipient responds, the item will not be fulfilled.
- For privacy, delivery details the recipient entered themselves (phone number, address) are returned as
nullin order query responses.
Physical shipping tracking
For MERCHANDISE products, once shipped, tracking appears in order_items[].delivery.shipping — { tracking_number, courier }.
Updated 19 days ago