Server API

Server API requires a secretKey and must never be used in the browser.

import { createServerClient } from '@01.software/sdk'

const serverClient = createServerClient({
  clientKey: process.env.NEXT_PUBLIC_SOFTWARE_CLIENT_KEY!,
  secretKey: process.env.SOFTWARE_SECRET_KEY!,
})

Orders API (`client.api`)

Method	Return Type	Description
`createOrder(params)`	`Promise<Order>`	Create an order
`updateOrder(params)`	`Promise<Order>`	Update order status
`getOrder(params)`	`Promise<Order>`	Get order by order number
`updateTransaction(params)`	`Promise<Transaction>`	Update transaction status
`checkout(params)`	`Promise<Order>`	Convert cart to order
`createFulfillment(params)`	`Promise<Fulfillment>`	Create shipment
`createReturn(params)`	`Promise<Return>`	Create a return request
`updateReturn(params)`	`Promise<Return>`	Update return status
`returnWithRefund(params)`	`Promise<{ return, transaction }>`	Return + refund in one call

createOrder()

import { generateOrderNumber } from '@01.software/sdk'

const order = await serverClient.api.createOrder({
  paymentId: 'pay_123456',
  orderNumber: generateOrderNumber(),
  email: 'customer@example.com',
  orderProducts: [
    { product: 'product_id', variant: 'variant_id', quantity: 2, price: 10000 }
  ],
  totalAmount: 20000,
  shippingAddress: { address: '123 Main St', zipCode: '10001' },
})

updateOrder()

const order = await serverClient.api.updateOrder({
  orderNumber: '260107482935',
  status: 'shipped',
})

Order status flow: pending → confirmed → shipped → delivered / cancelled

getOrder()

const order = await serverClient.api.getOrder({
  orderNumber: '260107482935',
})

updateTransaction()

const transaction = await serverClient.api.updateTransaction({
  paymentId: 'pay_123456',
  status: 'paid',
  paymentMethod: 'card',
  receiptUrl: 'https://receipt.example.com/123',
})

checkout()

Converts a cart to an order with payment info:

const order = await serverClient.api.checkout({
  cartId: 'cart_id',
  paymentId: 'pay_123456',
  orderNumber: generateOrderNumber(),
  customerSnapshot: {
    name: 'John Doe',
    email: 'john@example.com',
    phone: '010-1234-5678',
  },
})

createFulfillment()

Creates a shipment for an order:

const fulfillment = await serverClient.api.createFulfillment({
  orderNumber: '260107482935',
  carrier: 'cj',
  trackingNumber: '1234567890',
  items: [
    { orderProduct: 'order_product_id', quantity: 2 },
  ],
})

Carriers: cj, hanjin, lotte, epost, logen

createReturn()

const returnDoc = await serverClient.api.createReturn({
  orderNumber: '260107482935',
  reason: 'defective',
  reasonDetail: 'Screen cracked on arrival',
  returnProducts: [
    { orderProduct: 'order_product_id', quantity: 1 },
  ],
  refundAmount: 10000,
})

Reasons: change_of_mind, defective, wrong_delivery, damaged, other

updateReturn()

const returnDoc = await serverClient.api.updateReturn({
  returnId: 'return_id',
  status: 'approved',
})

Return status: requested → processing → approved / rejected → completed

returnWithRefund()

Combines return creation and refund transaction in one call:

const { return: returnDoc, transaction } = await serverClient.api.returnWithRefund({
  orderNumber: '260107482935',
  reason: 'defective',
  returnProducts: [
    { orderProduct: 'order_product_id', quantity: 1 },
  ],
  refundAmount: 10000,
  paymentId: 'pay_123456',
  refundReceiptUrl: 'https://receipt.example.com/refund/123',
})

Cart API (`client.cart`)

Cart API is available on both ServerClient (with secretKey) and BrowserClient (with customer token).

Method	Return Type	Description
`addItem(params)`	`Promise<CartItem>`	Add item to cart
`updateItem(params)`	`Promise<CartItem>`	Update item quantity
`removeItem(params)`	`Promise<{ success }>`	Remove item from cart

// Add item
const item = await client.cart.addItem({
  cartId: 'cart_id',
  product: 'product_id',
  variant: 'variant_id',
  option: 'option_id',
  quantity: 2,
})

// Update quantity
await client.cart.updateItem({
  cartItemId: item.id,
  quantity: 5,
})

// Remove
await client.cart.removeItem({
  cartItemId: item.id,
})

Product API (`client.product`)

Method	Return Type	Description
`stockCheck(params)`	`Promise<StockCheckResponse>`	Check stock for multiple options

const result = await serverClient.product.stockCheck({
  items: [
    { optionId: 'option_id_1', quantity: 2 },
    { optionId: 'option_id_2', quantity: 1 },
  ],
})

// result.allAvailable → boolean
// result.results → [{ optionId, available, availableStock, requestedQuantity, error? }]

Utilities

generateOrderNumber()

Generates an order number in YYMMDDRRRRRR format (12 digits).

import { generateOrderNumber } from '@01.software/sdk'

const orderNumber = generateOrderNumber() // "260107482935"

formatOrderName()

import { formatOrderName } from '@01.software/sdk'

formatOrderName([{ product: { title: 'iPhone' } }])
// → "iPhone"

formatOrderName([
  { product: { title: 'iPhone' } },
  { product: { title: 'AirPods' } },
])
// → "iPhone and 1 more"

resolveRelation()

Normalizes Payload relationship fields. Handles the case where depth: 0 returns an ID and depth > 0 returns an object.

import { resolveRelation } from '@01.software/sdk'

const author = resolveRelation(post.author) // Author | null

JWT / API Key

import { createServerToken, verifyServerToken, decodeServerToken, createApiKey, parseApiKey } from '@01.software/sdk/auth'

const token = await createServerToken(clientKey, secretKey)
const payload = await verifyServerToken(token, secretKey)
const decoded = decodeServerToken(token)  // Decode without verification
const apiKey = createApiKey(clientKey, secretKey)
const { clientKey, secretKey } = parseApiKey(apiKey)

01 Software

Server API

Server API

Orders API (`client.api`)

createOrder()

updateOrder()

getOrder()

updateTransaction()

checkout()

createFulfillment()

createReturn()

updateReturn()

returnWithRefund()

Cart API (`client.cart`)

Product API (`client.product`)

Utilities

generateOrderNumber()

formatOrderName()

resolveRelation()

JWT / API Key

On this page