Objects

The objects the API returns, field by field, and the difference between a benefit and a redeemable benefit.

This page is the API's dictionary: every object that shows up in a response, with all of its fields. Endpoint pages link here instead of repeating the lists.

The three codes

First of all, this: the API handles three similar-looking identifiers, and mixing them up is the most common mistake when integrating.

Code	What it identifies	Where it is used
`client_code`	A member. It is the number every person registered in Loybox has.	Recording a consumption, looking up a client
`benefit_id`	A catalog benefit, the one the commerce created.	Looking up a benefit, buying it
`client_benefit_code`	A benefit already bought by a specific member.	Looking up the code, redeeming it

A benefit and a redeemable benefit are not the same

The commerce creates benefits, and each one has a benefit_id. When a member buys one with their points they receive a redeemable benefit with its own client_benefit_code.

The benefit_id is only good for looking up information. The client_benefit_code is good for looking up and for redeeming: it is the code the member presents in the store, or pastes at the online store's checkout.

Client

Appears in listing clients and looking up a client.

codeintegerrequired

The member's code.

usernamestringrequired

The member's name.

emailstringrequired

The member's email.

pointsinteger | null

Points they hold at the commerce.

Benefit

The catalog benefit. Appears in almost every response of Benefits, Clients, My account and Public.

idstringrequired

The benefit_id.

typestringrequired

What kind of reward it is: percentage_discount, absolute_discount or free_product.

descriptionstringrequired

Description of the benefit.

costnumberrequired

How many points it costs to buy.

expirationdate-time | nullrequired

How long it stays valid. null if it does not expire.

benefit_typestring

normal for catalog ones; welcome, birthday, monthly_top or level for the automatic rewards. Defaults to normal.

colorstring | null

The commerce's brand color, in hexadecimal.

buy_limitinteger | null

Total number of redemptions allowed for this benefit. 0 means no limit.

prizePrize | null

The reward's detail. See Prize.

tiendanube_couponTiendanube coupon | null

The coupon, if the benefit applies in a Tiendanube store. See Tiendanube coupon.

Benefit (v2)

GET /v2/benefits/preview/{client_benefit_code} returns a version with three extra fields, which save you from digging into prize for the basics:

titlestringrequired

The benefit's title. In v1 it only lived inside prize.

valuenumber | null

The discount's value: the percentage if it is percentage_discount, the amount if it is absolute_discount.

productProduct | null

The product, if it is free_product. See Product.

Every other field is the same as in Benefit.

Redeemable benefit

A benefit a member already bought. Appears in purchased benefits, my benefits and as the response of buying a benefit.

client_benefit_codeintegerrequired

The redemption code. It is what the member presents at the commerce, and also the coupon code in an online store.

issue_datedate-timerequired

When they bought it.

due_datedate-time | null

How long they have to redeem it. null if it does not expire.

usedboolean

Whether it was already redeemed. Defaults to false.

benefitBenefitrequired

The benefit bought. See Benefit.

Prize

The detail of what the member wins. It lives inside prize.

typestringrequired

percentage_discount, absolute_discount or free_product.

titlestring | null

The reward's title.

descriptionstring | null

The reward's description.

valuenumber | null

The discount's percentage or amount, depending on the type.

productProduct | null

The gift product. See Product.

expirationdate-time | null

The reward's expiration.

imagestring | null

URL of the reward's image.

Product

idinteger | string | null

The product's id in Loybox.

namestring | null

The product's name.

external_idstring | null

The product's id in the commerce's own system.

Commerce

The program's branding data. Appears in commerce data and inside my account.

idintegerrequired

The commerce_id, the same one that goes in the X-Commerce-Id header.

namestringrequired

The commerce's name.

logostring | null

URL of the logo.

colorstring | null

Brand color in hexadecimal, for the program's UI.

category_namestring | null

The commerce's category, for example Tienda de comics.

currencystring | null

The commerce's currency.

My account

The response of GET /v1/me.

usernamestring | null

The user's name.

emailstring | null

The user's email.

phonestring | null

The user's phone.

pointsinteger

The user's points at this commerce. Defaults to 0.

subscribedboolean

Whether the user is subscribed to this commerce's program. Defaults to false.

commerceCommerce | null

The commerce's data, to paint the program's branding. See Commerce.

points_expirationPoints expiration | null

Points about to expire. See Points expiration.

Points expiration

pointsinteger

Points about to expire. Defaults to 0.

expiration_datedate-time | null

When they expire.

days_leftinteger | null

Days remaining.

months_leftinteger | null

Months remaining.

modestring | null

How points expire at this commerce: none, rolling or accumulated. none means they do not expire.

When points do not expire

If the commerce does not expire points, the object comes back with mode: "none" and points: 0, not as null. See Point expiration for the detail of the modes.

Tier

The response of GET /v1/me/level.

The endpoint and its fields say level; this documentation says "tier", which is the product's term in English. It is the same thing.

namestring | null

The tier's name.

rankinteger | null

The tier's position in the ladder.

points_multipliernumber | null

The points multiplier the tier grants.

icon_urlstring | null

URL of the tier's icon.

reached_atdate-time | null

When they reached the tier.

expiration_datedate-time | null

When the tier expires.

is_expiredboolean | null

Whether the tier already expired.

next_levelNext tier | null

The next tier and what is missing to reach it. See Next tier.

total_earned_pointsinteger | null

Points earned in total, the lifetime accumulated figure.

total_spent_amountnumber | null

Amount spent in total.

total_consumptions_countinteger | null

Number of consumptions recorded.

Next tier

namestring | null

The next tier's name.

rankinteger | null

The next tier's position.

threshold_typestring | null

What the threshold is measured in: accumulated points or amount spent.

thresholdnumber | null

The threshold value to reach.

Activity item

Each item of my history.

typestringrequired

What happened: consumption (a purchase that earned points), benefit_exchange (they bought a benefit with points), benefit_usage (they redeemed a benefit) or points_special_reward (an automatic reward gave them points).

datedate-time | null

When it happened.

pointsinteger | null

Points the item added or subtracted.

benefitBenefit | null

The benefit involved, on benefit items. See Benefit.

amountnumber | null

The purchase amount, on consumption items.

eventstring | null

The event that triggered the reward, on points_special_reward items.

additional_notestring | null

Additional note on the item.

Automatic reward

Each item of program rewards.

eventstringrequired

The event that triggers it: welcome, birthday or monthly_top.

reward_typestringrequired

benefit if it delivers a benefit, points if it delivers points.

benefitBenefit | null

The benefit it delivers, when reward_type is benefit. See Benefit.

pointsinteger | null

The points it delivers, when reward_type is points.

Session

The response of verifying the code.

accessstringrequired

Access token. Sent as Authorization: Bearer {access} on the My account endpoints.

refreshstringrequired

Refresh token, to get a new access without asking for another code.

expires_inintegerrequired

Seconds the access token stays valid.

user_idintegerrequired

The user's id.

usernamestring | null

The user's name.

emailstring | null

The user's email.

phonestring | null

The user's phone.

Tiendanube coupon

Lives inside tiendanube_coupon when the benefit applies in a Tiendanube store.

typestringrequired

percentage, absolute or shipping.

valuenumberrequired

The coupon's value.

categorystring | null

Id of the Tiendanube category the coupon applies to.

category_namestring | null

That category's name.

end_datedate-time | null

How long the coupon is valid for.

productTiendanube product | null

The product the coupon applies to, if it applies to a single one. See Tiendanube product.

Tiendanube product

tiendanube_idinteger | null

The product's id in Tiendanube.

namestring | null

The product's name.

urlstring | null

URL of the product in the store.

availableboolean | null

Whether it is in stock.

publishedboolean | null

Whether it is published in the store.

brandstring | null

The product's brand.

categoriesarray of categories

The product's categories, each with id and name. Empty by default.

On this page