Commerce · Docs

Products are what a brand promotes; samples get them into creators' hands.

Products

A brand's catalog comes from its Shopify connection or is added by hand with POST /v1/products. Prices are in cents. Set an accessCode to let creators redeem a product with a code instead of an order.

Attach products to a program in its promoted.products. Acting as a creator, GET /v1/products lists the products of the programs they're approved in; those are the ones they can request.

Samples

A creator requests a sample with { "product", "program" }. The brand approves or rejects it with PATCH /v1/samples/:id, and approving it places the order or shares the access code.

A brand can also send a sample directly:

TypeScript

await lucra.samples.create({
  body: {
    creator: "crtr_026UYfiw1Y6OvUpuKWiOpeL",
    product: "prod_04bst9MGXqblfqHhbR1iGGL",
    method: "order",
  },
})

method is order (a free Shopify order) or access_code. The creator reads the code with GET /v1/samples/:id?expand=accessCode.

Endpoints

GET/v1/products

As creatorread

List products; as a creator, the ones attached to the programs you're approved in, which you can ask a sample of

const { data } = await lucra.products.list()

Query parameters

Plus paging: limit, cursor, createdAfter and createdBefore.

Response200A page of items, 20 fields each, and nextCursorShow

idprod_…
accountacct_…
The brand whose catalog it's in.
brandNamestring
namestring
vendorstringnullable
productTypestringnullable
descriptionstringnullable
skustringnullable
statusstringnullable
active or archived; Shopify products can also be draft or unlisted.
urlstringnullable
imageUrlstringnullable
imagefile_…nullable
sampleEligibleboolean
accessCodestringnullable
A masked summary of the code creators get instead of an order.
variantsobject[]
Show 6 child fieldsHide child fields
- idstring
  The variant's ID in its store, as samples take it.
- titlestring
- optionstringnullable
- priceintegernullable
- skustringnullable
- imageUrlstringnullable
currencystringnullable
The currency of variant prices; null for manual products.
externalobjectnullable
The store the product syncs from; null for products added in Lucra.
Show 3 child fieldsHide child fields
- providerstring
  shopify
- idstring
- urlstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

POST/v1/products

write

Add a product to the catalog

const { data } = await lucra.products.create({
  body: { name: "…" },
})

Body

namestring· required
productTypestring
urlstring
descriptionstring
skustring
imagefile_…
sampleEligibleboolean
accessCodestring
statusenum
activearchived

Response20120 fieldsShow

idprod_…
accountacct_…
The brand whose catalog it's in.
brandNamestring
namestring
vendorstringnullable
productTypestringnullable
descriptionstringnullable
skustringnullable
statusstringnullable
active or archived; Shopify products can also be draft or unlisted.
urlstringnullable
imageUrlstringnullable
imagefile_…nullable
sampleEligibleboolean
accessCodestringnullable
A masked summary of the code creators get instead of an order.
variantsobject[]
Show 6 child fieldsHide child fields
- idstring
  The variant's ID in its store, as samples take it.
- titlestring
- optionstringnullable
- priceintegernullable
- skustringnullable
- imageUrlstringnullable
currencystringnullable
The currency of variant prices; null for manual products.
externalobjectnullable
The store the product syncs from; null for products added in Lucra.
Show 3 child fieldsHide child fields
- providerstring
  shopify
- idstring
- urlstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

GET/v1/products/:id

As creatorread

Get a product

const { data } = await lucra.products.retrieve({
  path: { id: "prod_…" },
})

Path parameters

idprod_…· required

Response20020 fieldsShow

idprod_…
accountacct_…
The brand whose catalog it's in.
brandNamestring
namestring
vendorstringnullable
productTypestringnullable
descriptionstringnullable
skustringnullable
statusstringnullable
active or archived; Shopify products can also be draft or unlisted.
urlstringnullable
imageUrlstringnullable
imagefile_…nullable
sampleEligibleboolean
accessCodestringnullable
A masked summary of the code creators get instead of an order.
variantsobject[]
Show 6 child fieldsHide child fields
- idstring
  The variant's ID in its store, as samples take it.
- titlestring
- optionstringnullable
- priceintegernullable
- skustringnullable
- imageUrlstringnullable
currencystringnullable
The currency of variant prices; null for manual products.
externalobjectnullable
The store the product syncs from; null for products added in Lucra.
Show 3 child fieldsHide child fields
- providerstring
  shopify
- idstring
- urlstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

PATCH/v1/products/:id

write

Edit, archive or set the access code of a product

const { data } = await lucra.products.update({
  path: { id: "prod_…" },
  body: { version: 1000 },
})

Path parameters

idprod_…· required

Body

versioninteger
namestring
productTypestring
urlstringnullable
descriptionstringnullable
skustringnullable
imagefile_…nullable
sampleEligibleboolean
accessCodestringnullable
statusenum
activearchived

Response20020 fieldsShow

idprod_…
accountacct_…
The brand whose catalog it's in.
brandNamestring
namestring
vendorstringnullable
productTypestringnullable
descriptionstringnullable
skustringnullable
statusstringnullable
active or archived; Shopify products can also be draft or unlisted.
urlstringnullable
imageUrlstringnullable
imagefile_…nullable
sampleEligibleboolean
accessCodestringnullable
A masked summary of the code creators get instead of an order.
variantsobject[]
Show 6 child fieldsHide child fields
- idstring
  The variant's ID in its store, as samples take it.
- titlestring
- optionstringnullable
- priceintegernullable
- skustringnullable
- imageUrlstringnullable
currencystringnullable
The currency of variant prices; null for manual products.
externalobjectnullable
The store the product syncs from; null for products added in Lucra.
Show 3 child fieldsHide child fields
- providerstring
  shopify
- idstring
- urlstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

GET/v1/samples

As creatorread

List samples

const { data } = await lucra.samples.list({
  query: { product: "prod_…" },
})

Query parameters

productprod_…
creatorcrtr_…
statusstring
One or more, comma-separated: requested, approved, rejected, shipping, shipped, failed.

Plus paging: limit, cursor, createdAfter and createdBefore.

Response200A page of items, 13 fields each, and nextCursorShow

idsmpl_…
creatorcrtr_…nullable
productprod_…nullable
productNamestring
The product's name when the sample was made, so it reads even if the product isn't one you can see.
variantobjectnullable
Show 2 child fieldsHide child fields
- idstringnullable
  The store's variant ID; null for products added in Lucra.
- titlestring
statusenum
requested, then approved or rejected by the brand; shipping once an order or access code is being made, then shipped, or failed.
requestedapprovedrejectedshippingshippedfailed
programprog_…nullable
notestringnullable
The creator's note with a request.
decidedAtstringnullable
shipmentobjectnullable
The order or access code that went out.
Show 8 child fieldsHide child fields
- statusenum
  The store's own progress: pending, invoice_pending, order_created, access_code_ready or failed.
  pendinginvoice_pendingorder_createdaccess_code_readyfailed
- methodenum
  orderaccess_code
- quantitynumber
- fulfillmentStatusstringnullable
- accessCodestringnullable
  Masked, unless the creator reads the sample with expand=accessCode.
- errorstringnullable
- orderobjectnullable
  Show 4 child fieldsHide child fields
  idstringnullable
  namestringnullable
  draftIdstringnullable
  shopDomainstring
- trackingobjectnullable
  Show 3 child fieldsHide child fields
  companystringnullable
  numberstring
  urlstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

POST/v1/samples

As creatorwrite

Request a sample as a creator, or send one to a creator as the brand

const { data } = await lucra.samples.create({
  body: { },
})

Response20113 fieldsShow

idsmpl_…
creatorcrtr_…nullable
productprod_…nullable
productNamestring
The product's name when the sample was made, so it reads even if the product isn't one you can see.
variantobjectnullable
Show 2 child fieldsHide child fields
- idstringnullable
  The store's variant ID; null for products added in Lucra.
- titlestring
statusenum
requested, then approved or rejected by the brand; shipping once an order or access code is being made, then shipped, or failed.
requestedapprovedrejectedshippingshippedfailed
programprog_…nullable
notestringnullable
The creator's note with a request.
decidedAtstringnullable
shipmentobjectnullable
The order or access code that went out.
Show 8 child fieldsHide child fields
- statusenum
  The store's own progress: pending, invoice_pending, order_created, access_code_ready or failed.
  pendinginvoice_pendingorder_createdaccess_code_readyfailed
- methodenum
  orderaccess_code
- quantitynumber
- fulfillmentStatusstringnullable
- accessCodestringnullable
  Masked, unless the creator reads the sample with expand=accessCode.
- errorstringnullable
- orderobjectnullable
  Show 4 child fieldsHide child fields
  idstringnullable
  namestringnullable
  draftIdstringnullable
  shopDomainstring
- trackingobjectnullable
  Show 3 child fieldsHide child fields
  companystringnullable
  numberstring
  urlstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

GET/v1/samples/:id

As creatorread

Get a sample; its creator can reveal an access code with expand=accessCode

const { data } = await lucra.samples.retrieve({
  path: { id: "smpl_…" },
  query: { expand: "accessCode" },
})

Path parameters

idsmpl_…· required

Query parameters

expandstring
As the creator: shipment.accessCode whole instead of masked. Each reveal is logged.
accessCode

Response20013 fieldsShow

idsmpl_…
creatorcrtr_…nullable
productprod_…nullable
productNamestring
The product's name when the sample was made, so it reads even if the product isn't one you can see.
variantobjectnullable
Show 2 child fieldsHide child fields
- idstringnullable
  The store's variant ID; null for products added in Lucra.
- titlestring
statusenum
requested, then approved or rejected by the brand; shipping once an order or access code is being made, then shipped, or failed.
requestedapprovedrejectedshippingshippedfailed
programprog_…nullable
notestringnullable
The creator's note with a request.
decidedAtstringnullable
shipmentobjectnullable
The order or access code that went out.
Show 8 child fieldsHide child fields
- statusenum
  The store's own progress: pending, invoice_pending, order_created, access_code_ready or failed.
  pendinginvoice_pendingorder_createdaccess_code_readyfailed
- methodenum
  orderaccess_code
- quantitynumber
- fulfillmentStatusstringnullable
- accessCodestringnullable
  Masked, unless the creator reads the sample with expand=accessCode.
- errorstringnullable
- orderobjectnullable
  Show 4 child fieldsHide child fields
  idstringnullable
  namestringnullable
  draftIdstringnullable
  shopDomainstring
- trackingobjectnullable
  Show 3 child fieldsHide child fields
  companystringnullable
  numberstring
  urlstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring

PATCH/v1/samples/:id

write

Approve or reject a sample request

const { data } = await lucra.samples.update({
  path: { id: "smpl_…" },
  body: { status: "approved" },
})

Path parameters

idsmpl_…· required

Body

statusenum· required
approvedrejected
versioninteger

Response20013 fieldsShow

idsmpl_…
creatorcrtr_…nullable
productprod_…nullable
productNamestring
The product's name when the sample was made, so it reads even if the product isn't one you can see.
variantobjectnullable
Show 2 child fieldsHide child fields
- idstringnullable
  The store's variant ID; null for products added in Lucra.
- titlestring
statusenum
requested, then approved or rejected by the brand; shipping once an order or access code is being made, then shipped, or failed.
requestedapprovedrejectedshippingshippedfailed
programprog_…nullable
notestringnullable
The creator's note with a request.
decidedAtstringnullable
shipmentobjectnullable
The order or access code that went out.
Show 8 child fieldsHide child fields
- statusenum
  The store's own progress: pending, invoice_pending, order_created, access_code_ready or failed.
  pendinginvoice_pendingorder_createdaccess_code_readyfailed
- methodenum
  orderaccess_code
- quantitynumber
- fulfillmentStatusstringnullable
- accessCodestringnullable
  Masked, unless the creator reads the sample with expand=accessCode.
- errorstringnullable
- orderobjectnullable
  Show 4 child fieldsHide child fields
  idstringnullable
  namestringnullable
  draftIdstringnullable
  shopDomainstring
- trackingobjectnullable
  Show 3 child fieldsHide child fields
  companystringnullable
  numberstring
  urlstringnullable
versioninteger
Send it back on PATCH to reject edits based on a stale read.
createdAtstring
updatedAtstring