Punchcommerce medusa plugin

PunchOut за считаные минуты, без предварительного опыта. Подключает Medusa v2 к системам закупок через OCI, cXML и IDS-Connect.

npm install @punchcommerce/punchcommerce-medusa-plugin

Категория

Другое

Создано

Punchcommerce

Версия

0.2.2

Последнее обновление

6 дней назад

Ежемесячные загрузки

Звезды на Github

NPM

PunchCommerce Plugin for Medusa

A Medusa v2 plugin that integrates with PunchCommerce to enable cXML/PunchOut procurement gateway functionality. Procurement systems redirect buyers to your Medusa storefront where they can browse and add items to a cart, then transfer the cart back to the procurement system.

How It Works

Buyer clicks a PunchOut link in their ERP → PunchCommerce redirects to your storefront's entry route with and query parameters
Storefront authenticates the buyer via the Medusa SDK using the auth provider ()
Storefront creates a fresh cart for the session and stores in . The buyer shops normally — items are added through the standard Store API.
On checkout, the storefront calls to receive the PunchOut basket payload + a , then submits the basket as a form to that URL.

Installation

Requires Medusa v2.13.6 or newer (any 2.x release).

npm install @punchcommerce/punchcommerce-medusa-plugin

Configuration

The plugin requires you to add two entries to your : the plugin itself and an auth provider inside the Auth module.

Add the plugin to :

1plugins: [
   // ... other plugins
  {
    resolve: "@punchcommerce/punchcommerce-medusa-plugin",
    options: {
      punchcommerceUrl: process.env.PUNCHCOMMERCE_URL,
    },
  },
]

1// medusa-config.ts
2module.exports = defineConfig({
modules: [
  {
    resolve: "@medusajs/medusa/auth",
    options: {
      providers: [
         // ... other providers
        {
          resolve: "@punchcommerce/punchcommerce-medusa-plugin/providers/punchcommerce-auth",
          id: "punchcommerce",
          options: {
            punchcommerceUrl: process.env.PUNCHCOMMERCE_URL,
            disableSessionValidation: false, // never disable in production
          },
        },
      ],
    },
  },
],
21})

Options

Option	Required	Default	Description
	No		Base URL of the PunchCommerce gateway. Override for staging or self-hosted instances. Pass to both the plugin entry and the auth-provider entry.
	No		Auth-provider option. When , skips the call to and accepts any well-formed . Intended for local development without a live PunchCommerce instance — never enable in production.

Note: the gateway version is currently pinned to (see ).

Customer Setup

Customers are linked to PunchCommerce via an identity in Medusa's Auth module.

In PunchCommerce: create a customer and copy the Customer identification — this is the .
In Medusa admin: open the customer's detail page. On the right sidebar, the PunchCommerce widget shows the current link.
- Click Add (or the pencil icon) and paste the .
- If the same is already linked to another customer, the API returns an error and the widget displays it.
- Use the trash icon to unlink. The link is also auto-removed when the customer is deleted.

PunchCommerce Configuration

In the PunchCommerce dashboard, configure each customer with:

Entry address: your storefront's PunchOut landing route, e.g.
Customer identification: the same you entered in the Medusa admin

PunchCommerce will redirect buyers to the entry address with appended (plus any action parameters).

Storefront Requirements

The plugin is backend-only. The storefront must orchestrate the PunchOut flow.

1. Authentication route

Create a route that PunchCommerce redirects to. It must call the Medusa SDK with the provider and persist the auth token + .

All examples use the Next.js Starter Template: https://github.com/medusajs/nextjs-starter-medusa

1// app/[region]/punchcommerce/authenticate/route.ts (Next.js)
2import { sdk } from "@lib/config"
3import { setAuthToken } from "@lib/data/cookies"
4import { NextRequest, NextResponse } from "next/server"
5
6export async function GET(request: NextRequest) {
7  const sID = request.nextUrl.searchParams.get("sID")
8  const uID = request.nextUrl.searchParams.get("uID")
9  if (!sID || !uID) {
10    // you can also render a error-page here  
11    return NextResponse.json({ error: "Missing sID or uID" }, { status: 400 })
12  }
13
14  const token = await sdk.auth.login("customer", "punchcommerce", { sID, uID })
15  if (typeof token !== "string") {
16    // you can also render a custom error-page here  
17    return NextResponse.json({ error: "Authentication failed" }, { status: 401 })
18  }
19
20  await setAuthToken(token)
21  const res = NextResponse.redirect(new URL("/store", process.env.NEXT_PUBLIC_BASE_URL))
22   
23  return res
24}

What this triggers in the backend (see ):

The is validated against (unless is set).
The provider identity is looked up by . If no customer has that linked, the request fails with .
On success, Medusa returns an auth token scoped to the linked customer.

2. Session-scoped cart

After authentication, create a new cart for the PunchOut session and attach the to its metadata. All Store API operations referencing this cart inherit the link.

1const { cart } = await sdk.store.cart.create({ region_id, currency_code: "eur" })
2await sdk.store.cart.update(cart.id, {
3  metadata: { punchcommerce_session_id: sID },
4})

Existing carts the customer owns outside of PunchOut are untouched. enforces that the cart used for any transfer/action has set.

3. PunchOut Page (replaces checkout)

Instead of the normal checkout, render a dedicated page that loads the prepared basket from the backend, shows it to the buyer for review, and submits it to PunchCommerce via a form on click. The buyer never sees the JSON payload — only the cart summary and a "Submit to procurement" button.

Data loader (server action that hits the Store API):

1// lib/data/punchcommerce.ts
2"use server"
3import { sdk } from "@lib/config"
4import { getAuthHeaders, getCartId } from "./cookies"
5
6export async function getPunchOutBasket() {
7  const cartId = await getCartId()
8  if (!cartId) return null
9
10  return sdk.client.fetch<{ basket: PunchOutPosition[]; punchoutUrl: string }>(
11    `/store/punchout/basket`,
12    {
13      method: "GET",
14      cache: "no-store",
15      query: { cart_id: cartId },
16      headers: { ...(await getAuthHeaders()) },
17    }
18  )
19}

PunchOut Page:

1// app/[countryCode]/(main)/punchout/page.tsx
2export default async function PunchOutPage() {
const data = await getPunchOutBasket()
if (!data) return notFound()
5
const { basket, punchoutUrl } = data
7
return (
  <div>
    <h1>Complete PunchOut</h1>
    <ul>
      {basket.map((item, i) => (
        <li key={i}>
          {item.quantity} × {item.product_name} ({item.product_ordernumber})
        </li>
      ))}
    </ul>
18
    <form action={punchoutUrl} method="POST">
      {/* The hidden field MUST wrap the array in `{ basket }` — that is the
          shape PunchCommerce's /gateway/v3/return endpoint expects. */}
      <input type="hidden" name="basket" value={JSON.stringify({ basket })} />
      <button type="submit">Submit to procurement</button>
    </form>
  </div>
)
27}

4. PunchOut Actions (optional)

PunchCommerce can append to the entry URL to ask the storefront to perform additional steps right after authentication. The backend exposes to process them and the storefront decides what to do with the response.

Action	Required params	Effect
		Adds the listed items to the current cart. Missing SKUs return as warning notifications.
		Looks up the product handle for the SKU. Storefront redirects to the product-detail page.
		Storefront redirects to its own search results page.
		Backend builds a basket from search results and returns it together with a (for inline PunchOut sessions that submit search results back).

A few things to keep in mind before implementing:

always runs when present, regardless of other actions. It mutates the cart and may add notifications for missing SKUs. It never sets a navigation response.
Only the first result-producing action wins. If contains both and , the backend processes the first one and skips the rest.
The input action name is (hyphen) but the response discriminant is (underscore) — always branch on , not the raw input string.
(e.g. "SKU X not found") survive the action call even when a redirect follows. Store them in a cookie or flash session to surface them to the buyer after the redirect.

Data loader (add alongside in ):

Note: In the authenticate route the auth token and cart were just created, so / may not yet read the freshly-set cookies. Pass both values explicitly from the route; the defaults still work for other callers (e.g. loading the loader from the page after the session is established).

1// lib/data/punchcommerce.ts
2"use server"
3import { sdk } from "@lib/config"
4import { getAuthHeaders, getCartId } from "./cookies"
5
6type PunchOutActionNotification = { type: "info" | "warning"; message: string }
7type PunchOutActionResponse =
8  | { type: "default" }
9  | { type: "detail"; product_handle: string }
10  | { type: "search"; keyword: string }
11  | { type: "background_search"; basket: PunchOutPosition[]; punchoutUrl: string }
12
13export async function processPunchOutActions(
14  params: URLSearchParams,
15  opts: { cartId?: string; authHeaders?: Record<string, string> } = {}
16): Promise<{ notifications: PunchOutActionNotification[]; response: PunchOutActionResponse } | null> {
17  const cartId = opts.cartId ?? (await getCartId())
18  if (!cartId) return null
19  const headers = opts.authHeaders ?? { ...(await getAuthHeaders()) }
20
21  // Forward all action params (actions[], items, ordernumber, keyword) plus the cart.
22  const query = new URLSearchParams(params)
23  query.set("cart_id", cartId)
24
25  return sdk.client.fetch(`/store/punchout/actions?${query.toString()}`, {
26    method: "GET",
27    cache: "no-store",
28    headers,
29  })
30}

Extended authenticate route — after and cart creation (Steps 1–2), check for actions and branch on the result:

1// app/[countryCode]/punchcommerce/authenticate/route.ts (extended from Step 1)
2import { sdk } from "@lib/config"
3import { getCacheTag, setAuthToken, setCartId } from "@lib/data/cookies"
4import { processPunchOutActions, PunchOutPosition } from "@lib/data/punchcommerce"
5import { NextRequest, NextResponse } from "next/server"
6
7// Renders a page that auto-submits a POST form to PunchCommerce on load.
8// Used for background_search, where the buyer never reviews the basket manually.
9function renderAutoSubmitForm(punchoutUrl: string, basket: PunchOutPosition[]) {
// Escape double-quotes so the JSON is safe inside an HTML attribute value.
const payload = JSON.stringify({ basket }).replace(/"/g, "&quot;")
return `<!doctype html><html><body onload="document.forms[0].submit()">
  <form action="${punchoutUrl}" method="POST">
    <input type="hidden" name="basket" value="${payload}" />
    <noscript><button type="submit">Submit to procurement</button></noscript>
  </form>
</body></html>`
18}
19
20export async function GET(request: NextRequest, { params }) {
const { countryCode } = await params
const url = request.nextUrl
const sID = url.searchParams.get("sID")
const uID = url.searchParams.get("uID")
if (!sID || !uID) {
  return NextResponse.json({ error: "Missing sID or uID" }, { status: 400 })
}
28
const token = await sdk.auth.login("customer", "punchcommerce", { sID, uID })
if (typeof token !== "string") {
  return NextResponse.json({ error: "Authentication failed" }, { status: 401 })
}
33
await setAuthToken(token)
35
// Step 2: create a new session-scoped cart with punchcommerce_session_id in metadata.
const authHeaders = { authorization: `Bearer ${token}` }
const { cart } = await sdk.store.cart.create(
  { region_id, metadata: { punchcommerce_session_id: sID } },
  {},
  authHeaders
)
await setCartId(cart.id)
44
const baseUrl = process.env.NEXT_PUBLIC_BASE_URL!
const hasActions = url.searchParams.has("actions[]") || url.searchParams.has("actions")
47
if (!hasActions) {
  return NextResponse.redirect(new URL(`/${countryCode}/store`, baseUrl))
}
51
// Pass cart.id and the token explicitly — cookies are not yet readable in this request.
const dispatch = await processPunchOutActions(url.searchParams, {
  cartId: cart.id,
  authHeaders,
})
const response = dispatch?.response ?? { type: "default" as const }
58
switch (response.type) {
  case "detail":
    return NextResponse.redirect(
      new URL(`/${countryCode}/products/${response.product_handle}`, baseUrl)
    )
64
  case "search":
    // Redirect to the store page with a search keyword.
    return NextResponse.redirect(
      new URL(`/${countryCode}/store?q=${encodeURIComponent(response.keyword)}`, baseUrl)
    )
70
  case "background_search":
    // The backend already built a basket from the keyword search results.
    // Return an auto-submitting page so the browser POSTs the basket straight to
    // PunchCommerce — the basket MUST be wrapped in { basket } (same as Step 3).
    return new NextResponse(
      renderAutoSubmitForm(response.punchoutUrl, response.basket),
      { headers: { "content-type": "text/html" } }
    )
79
  default:
    // restore-basket ran (if requested) but set no navigation response — go to the store.
    return NextResponse.redirect(new URL(`/${countryCode}/store`, baseUrl))
}
84}

Also see https://www.punchcommerce.de/swagger#/E-Commerce-Integration/post_punchcommerce_authenticate

Cart Mapping

The plugin maps each Medusa cart line item to a ():

= the line (net), = (gross), = (net unit price)
is forwarded from the cart line (decimal, e.g. )
is truncated to 39 characters (OCI/cXML constraint)
is hardcoded to ; per-variant unit mapping (, , , …) is not yet implemented
The basket is submitted to as by the storefront

Cart Lifecycle

After a successful transfer, the Medusa cart is not automatically marked complete, archived, or deleted — it remains in its current state. Recommended storefront behavior:

Start the next PunchOut session by creating a brand-new cart with the new in its metadata

(The actual purchase order is created later through PunchCommerce / the ERP — Medusa is only the catalog browsing surface.)

Parallel Sessions

Carts are scoped per , not per customer, so a single PunchCommerce-linked customer can have multiple independent PunchOut sessions in flight.

REST API Reference

Customer-authenticated (bearer or session). Builds a PunchOut basket from a session-scoped Medusa cart.

Query	Required	Description
	Yes	Cart whose metadata contains .

Response:

Customer-authenticated. Processes one or more PunchOut entry actions.

Query	Required	Description
	Yes	Cart to operate on.
	Yes	One or more of , , , .
	For	Comma-separated pairs.
	For	SKU to look up.
	For /	Free-text search term.

Response: — see .

Admin-authenticated. Backs the customer-detail widget.

GET →
POST body — upserts the link.
DELETE — removes the link.

Types Reference

All types are exported from .

A single line in the PunchOut basket. The plugin builds one position per Medusa cart line item.

1type PunchOutPosition = {
product_ordernumber: string   // SKU of the variant; primary key in PunchCommerce
product_name: string          // Display name, truncated to 39 chars (OCI/cXML limit)
quantity: number              // Whole-unit count for this line
item_price: number            // Net unit price (= price_net / quantity)
price: number                 // Gross line total (with tax) — Medusa's `line.total`
price_net: number             // Net line total (without tax) — Medusa's `line.subtotal`
tax_rate: number              // Decimal tax rate, e.g. 0.19 for 19%
type: "product" | "shipping-costs"  // "shipping-costs" reserved; currently all lines are products
product: PunchOutProduct      // Embedded product master data (see below)
11}

Product-Data embedded in each PunchOutPosition. Sent to PunchCommerce so the procurement system can store/display the product even if the buyer's catalog doesn't have it.

1type PunchOutProduct = {
id: string                    // Internal product id (Medusa product_id) — informational
ordernumber: string           // SKU — duplicates PunchOutPosition.product_ordernumber
brand_ordernumber: string     // Manufacturer ordering reference; currently same as `ordernumber`
title: string                 // Full untruncated product title
description: string           // Plain-text product description
image_url?: string | null     // Variant or product thumbnail URL
price: number                 // Net unit price (mirrors PunchOutPosition.item_price)
currency: string              // ISO 4217 code, lowercase (e.g. "eur") — taken from the cart
tax_rate: number              // Same decimal value as PunchOutPosition.tax_rate
packaging_unit: string        // Hardcoded "Piece" today; future: per-variant mapping
shipping_time: number         // Hardcoded 0 today
active: "true" | "false"      // String (not boolean) — PunchCommerce convention
14
// Optional fields — not populated by this plugin yet, but accepted by PunchCommerce:
brand?: string
customer_ordernumber?: string
category?: string
description_long?: string
purchase_unit?: number
reference_unit?: number
unit?: string                 // OCI unit code, e.g. "PCE", "KG", "LTR"
unit_name?: string            // Human-readable unit name
weight?: number
classification_type?: string
classification?: string
27}

Top-level basket wrapper. This is the shape the PunchCommerce endpoint expects — when submitting the form, wrap the position array in .

1type PunchOutBasket = {
2  basket: PunchOutPosition[]
3}

Item passed to the action. The route parses the query string into an array of these.

1type PunchOutActionItem = {
2  sku: string
3  quantity: number
4}

Warning / info message returned alongside an action response (e.g. when a SKU in was not found).

1type PunchOutActionNotification = {
2  type: "info" | "warning"
3  message: string
4}

Discriminated union returned by . The storefront branches on to decide what to do next.

1type PunchOutActionResponse =
| { type: "default" }                                   // No action produced a result — proceed normally
| { type: "detail"; product_handle: string }            // Redirect the buyer to the PDP at this handle
| { type: "search"; keyword: string }                   // Redirect to your storefront's search page
| {                                                     // Inline-search PunchOut: submit the returned basket
    type: "background_search"
    basket: PunchOutPosition[]
    punchoutUrl: string
  }

Еще в этой категории

Посмотреть все

Другое

Gati

От Devx Commerce

Синхронизируйте Medusa с Gati ERP

Другое

Product Reviews

От Lambda Curry

Добавляйте рейтинги, отзывы и модерацию товаров

Другое

Variant Images

От Betanoir

Организуйте и загружайте варианты изображений в Medusa

Плагины

Punchcommerce medusa plugin

PunchOut за считаные минуты, без предварительного опыта. Подключает Medusa v2 к системам закупок через OCI, cXML и IDS-Connect.

npm install @punchcommerce/punchcommerce-medusa-plugin

Категория

Другое

Создано

Punchcommerce

Версия

0.2.2

Последнее обновление

6 дней назад

Ежемесячные загрузки

Звезды на Github

NPM

PunchCommerce Plugin for Medusa

How It Works

Buyer clicks a PunchOut link in their ERP → PunchCommerce redirects to your storefront's entry route with and query parameters
Storefront authenticates the buyer via the Medusa SDK using the auth provider ()
Storefront creates a fresh cart for the session and stores in . The buyer shops normally — items are added through the standard Store API.
On checkout, the storefront calls to receive the PunchOut basket payload + a , then submits the basket as a form to that URL.

Installation

Requires Medusa v2.13.6 or newer (any 2.x release).

npm install @punchcommerce/punchcommerce-medusa-plugin

Configuration

The plugin requires you to add two entries to your : the plugin itself and an auth provider inside the Auth module.

Add the plugin to :

1plugins: [
   // ... other plugins
  {
    resolve: "@punchcommerce/punchcommerce-medusa-plugin",
    options: {
      punchcommerceUrl: process.env.PUNCHCOMMERCE_URL,
    },
  },
]

1// medusa-config.ts
2module.exports = defineConfig({
modules: [
  {
    resolve: "@medusajs/medusa/auth",
    options: {
      providers: [
         // ... other providers
        {
          resolve: "@punchcommerce/punchcommerce-medusa-plugin/providers/punchcommerce-auth",
          id: "punchcommerce",
          options: {
            punchcommerceUrl: process.env.PUNCHCOMMERCE_URL,
            disableSessionValidation: false, // never disable in production
          },
        },
      ],
    },
  },
],
21})

Options

Option	Required	Default	Description
	No		Base URL of the PunchCommerce gateway. Override for staging or self-hosted instances. Pass to both the plugin entry and the auth-provider entry.
	No		Auth-provider option. When , skips the call to and accepts any well-formed . Intended for local development without a live PunchCommerce instance — never enable in production.

Note: the gateway version is currently pinned to (see ).

Customer Setup

Customers are linked to PunchCommerce via an identity in Medusa's Auth module.

In PunchCommerce: create a customer and copy the Customer identification — this is the .
In Medusa admin: open the customer's detail page. On the right sidebar, the PunchCommerce widget shows the current link.
- Click Add (or the pencil icon) and paste the .
- If the same is already linked to another customer, the API returns an error and the widget displays it.
- Use the trash icon to unlink. The link is also auto-removed when the customer is deleted.

PunchCommerce Configuration

In the PunchCommerce dashboard, configure each customer with:

Entry address: your storefront's PunchOut landing route, e.g.
Customer identification: the same you entered in the Medusa admin

PunchCommerce will redirect buyers to the entry address with appended (plus any action parameters).

Storefront Requirements

The plugin is backend-only. The storefront must orchestrate the PunchOut flow.

1. Authentication route

Create a route that PunchCommerce redirects to. It must call the Medusa SDK with the provider and persist the auth token + .

All examples use the Next.js Starter Template: https://github.com/medusajs/nextjs-starter-medusa

1// app/[region]/punchcommerce/authenticate/route.ts (Next.js)
2import { sdk } from "@lib/config"
3import { setAuthToken } from "@lib/data/cookies"
4import { NextRequest, NextResponse } from "next/server"
5
6export async function GET(request: NextRequest) {
7  const sID = request.nextUrl.searchParams.get("sID")
8  const uID = request.nextUrl.searchParams.get("uID")
9  if (!sID || !uID) {
10    // you can also render a error-page here  
11    return NextResponse.json({ error: "Missing sID or uID" }, { status: 400 })
12  }
13
14  const token = await sdk.auth.login("customer", "punchcommerce", { sID, uID })
15  if (typeof token !== "string") {
16    // you can also render a custom error-page here  
17    return NextResponse.json({ error: "Authentication failed" }, { status: 401 })
18  }
19
20  await setAuthToken(token)
21  const res = NextResponse.redirect(new URL("/store", process.env.NEXT_PUBLIC_BASE_URL))
22   
23  return res
24}

What this triggers in the backend (see ):

The is validated against (unless is set).
The provider identity is looked up by . If no customer has that linked, the request fails with .
On success, Medusa returns an auth token scoped to the linked customer.

2. Session-scoped cart

After authentication, create a new cart for the PunchOut session and attach the to its metadata. All Store API operations referencing this cart inherit the link.

1const { cart } = await sdk.store.cart.create({ region_id, currency_code: "eur" })
2await sdk.store.cart.update(cart.id, {
3  metadata: { punchcommerce_session_id: sID },
4})

Existing carts the customer owns outside of PunchOut are untouched. enforces that the cart used for any transfer/action has set.

3. PunchOut Page (replaces checkout)

Data loader (server action that hits the Store API):

1// lib/data/punchcommerce.ts
2"use server"
3import { sdk } from "@lib/config"
4import { getAuthHeaders, getCartId } from "./cookies"
5
6export async function getPunchOutBasket() {
7  const cartId = await getCartId()
8  if (!cartId) return null
9
10  return sdk.client.fetch<{ basket: PunchOutPosition[]; punchoutUrl: string }>(
11    `/store/punchout/basket`,
12    {
13      method: "GET",
14      cache: "no-store",
15      query: { cart_id: cartId },
16      headers: { ...(await getAuthHeaders()) },
17    }
18  )
19}

PunchOut Page:

1// app/[countryCode]/(main)/punchout/page.tsx
2export default async function PunchOutPage() {
const data = await getPunchOutBasket()
if (!data) return notFound()
5
const { basket, punchoutUrl } = data
7
return (
  <div>
    <h1>Complete PunchOut</h1>
    <ul>
      {basket.map((item, i) => (
        <li key={i}>
          {item.quantity} × {item.product_name} ({item.product_ordernumber})
        </li>
      ))}
    </ul>
18
    <form action={punchoutUrl} method="POST">
      {/* The hidden field MUST wrap the array in `{ basket }` — that is the
          shape PunchCommerce's /gateway/v3/return endpoint expects. */}
      <input type="hidden" name="basket" value={JSON.stringify({ basket })} />
      <button type="submit">Submit to procurement</button>
    </form>
  </div>
)
27}

4. PunchOut Actions (optional)

Action	Required params	Effect
		Adds the listed items to the current cart. Missing SKUs return as warning notifications.
		Looks up the product handle for the SKU. Storefront redirects to the product-detail page.
		Storefront redirects to its own search results page.
		Backend builds a basket from search results and returns it together with a (for inline PunchOut sessions that submit search results back).

A few things to keep in mind before implementing:

always runs when present, regardless of other actions. It mutates the cart and may add notifications for missing SKUs. It never sets a navigation response.
Only the first result-producing action wins. If contains both and , the backend processes the first one and skips the rest.
The input action name is (hyphen) but the response discriminant is (underscore) — always branch on , not the raw input string.
(e.g. "SKU X not found") survive the action call even when a redirect follows. Store them in a cookie or flash session to surface them to the buyer after the redirect.

Data loader (add alongside in ):

Note: In the authenticate route the auth token and cart were just created, so / may not yet read the freshly-set cookies. Pass both values explicitly from the route; the defaults still work for other callers (e.g. loading the loader from the page after the session is established).

1// lib/data/punchcommerce.ts
2"use server"
3import { sdk } from "@lib/config"
4import { getAuthHeaders, getCartId } from "./cookies"
5
6type PunchOutActionNotification = { type: "info" | "warning"; message: string }
7type PunchOutActionResponse =
8  | { type: "default" }
9  | { type: "detail"; product_handle: string }
10  | { type: "search"; keyword: string }
11  | { type: "background_search"; basket: PunchOutPosition[]; punchoutUrl: string }
12
13export async function processPunchOutActions(
14  params: URLSearchParams,
15  opts: { cartId?: string; authHeaders?: Record<string, string> } = {}
16): Promise<{ notifications: PunchOutActionNotification[]; response: PunchOutActionResponse } | null> {
17  const cartId = opts.cartId ?? (await getCartId())
18  if (!cartId) return null
19  const headers = opts.authHeaders ?? { ...(await getAuthHeaders()) }
20
21  // Forward all action params (actions[], items, ordernumber, keyword) plus the cart.
22  const query = new URLSearchParams(params)
23  query.set("cart_id", cartId)
24
25  return sdk.client.fetch(`/store/punchout/actions?${query.toString()}`, {
26    method: "GET",
27    cache: "no-store",
28    headers,
29  })
30}

Extended authenticate route — after and cart creation (Steps 1–2), check for actions and branch on the result:

1// app/[countryCode]/punchcommerce/authenticate/route.ts (extended from Step 1)
2import { sdk } from "@lib/config"
3import { getCacheTag, setAuthToken, setCartId } from "@lib/data/cookies"
4import { processPunchOutActions, PunchOutPosition } from "@lib/data/punchcommerce"
5import { NextRequest, NextResponse } from "next/server"
6
7// Renders a page that auto-submits a POST form to PunchCommerce on load.
8// Used for background_search, where the buyer never reviews the basket manually.
9function renderAutoSubmitForm(punchoutUrl: string, basket: PunchOutPosition[]) {
// Escape double-quotes so the JSON is safe inside an HTML attribute value.
const payload = JSON.stringify({ basket }).replace(/"/g, "&quot;")
return `<!doctype html><html><body onload="document.forms[0].submit()">
  <form action="${punchoutUrl}" method="POST">
    <input type="hidden" name="basket" value="${payload}" />
    <noscript><button type="submit">Submit to procurement</button></noscript>
  </form>
</body></html>`
18}
19
20export async function GET(request: NextRequest, { params }) {
const { countryCode } = await params
const url = request.nextUrl
const sID = url.searchParams.get("sID")
const uID = url.searchParams.get("uID")
if (!sID || !uID) {
  return NextResponse.json({ error: "Missing sID or uID" }, { status: 400 })
}
28
const token = await sdk.auth.login("customer", "punchcommerce", { sID, uID })
if (typeof token !== "string") {
  return NextResponse.json({ error: "Authentication failed" }, { status: 401 })
}
33
await setAuthToken(token)
35
// Step 2: create a new session-scoped cart with punchcommerce_session_id in metadata.
const authHeaders = { authorization: `Bearer ${token}` }
const { cart } = await sdk.store.cart.create(
  { region_id, metadata: { punchcommerce_session_id: sID } },
  {},
  authHeaders
)
await setCartId(cart.id)
44
const baseUrl = process.env.NEXT_PUBLIC_BASE_URL!
const hasActions = url.searchParams.has("actions[]") || url.searchParams.has("actions")
47
if (!hasActions) {
  return NextResponse.redirect(new URL(`/${countryCode}/store`, baseUrl))
}
51
// Pass cart.id and the token explicitly — cookies are not yet readable in this request.
const dispatch = await processPunchOutActions(url.searchParams, {
  cartId: cart.id,
  authHeaders,
})
const response = dispatch?.response ?? { type: "default" as const }
58
switch (response.type) {
  case "detail":
    return NextResponse.redirect(
      new URL(`/${countryCode}/products/${response.product_handle}`, baseUrl)
    )
64
  case "search":
    // Redirect to the store page with a search keyword.
    return NextResponse.redirect(
      new URL(`/${countryCode}/store?q=${encodeURIComponent(response.keyword)}`, baseUrl)
    )
70
  case "background_search":
    // The backend already built a basket from the keyword search results.
    // Return an auto-submitting page so the browser POSTs the basket straight to
    // PunchCommerce — the basket MUST be wrapped in { basket } (same as Step 3).
    return new NextResponse(
      renderAutoSubmitForm(response.punchoutUrl, response.basket),
      { headers: { "content-type": "text/html" } }
    )
79
  default:
    // restore-basket ran (if requested) but set no navigation response — go to the store.
    return NextResponse.redirect(new URL(`/${countryCode}/store`, baseUrl))
}
84}

Also see https://www.punchcommerce.de/swagger#/E-Commerce-Integration/post_punchcommerce_authenticate

Cart Mapping

The plugin maps each Medusa cart line item to a ():

= the line (net), = (gross), = (net unit price)
is forwarded from the cart line (decimal, e.g. )
is truncated to 39 characters (OCI/cXML constraint)
is hardcoded to ; per-variant unit mapping (, , , …) is not yet implemented
The basket is submitted to as by the storefront

Cart Lifecycle

After a successful transfer, the Medusa cart is not automatically marked complete, archived, or deleted — it remains in its current state. Recommended storefront behavior:

Start the next PunchOut session by creating a brand-new cart with the new in its metadata

(The actual purchase order is created later through PunchCommerce / the ERP — Medusa is only the catalog browsing surface.)

Parallel Sessions

Carts are scoped per , not per customer, so a single PunchCommerce-linked customer can have multiple independent PunchOut sessions in flight.

REST API Reference

Customer-authenticated (bearer or session). Builds a PunchOut basket from a session-scoped Medusa cart.

Query	Required	Description
	Yes	Cart whose metadata contains .

Response:

Customer-authenticated. Processes one or more PunchOut entry actions.

Query	Required	Description
	Yes	Cart to operate on.
	Yes	One or more of , , , .
	For	Comma-separated pairs.
	For	SKU to look up.
	For /	Free-text search term.

Response: — see .

Admin-authenticated. Backs the customer-detail widget.

GET →
POST body — upserts the link.
DELETE — removes the link.

Types Reference

All types are exported from .

A single line in the PunchOut basket. The plugin builds one position per Medusa cart line item.

1type PunchOutPosition = {
product_ordernumber: string   // SKU of the variant; primary key in PunchCommerce
product_name: string          // Display name, truncated to 39 chars (OCI/cXML limit)
quantity: number              // Whole-unit count for this line
item_price: number            // Net unit price (= price_net / quantity)
price: number                 // Gross line total (with tax) — Medusa's `line.total`
price_net: number             // Net line total (without tax) — Medusa's `line.subtotal`
tax_rate: number              // Decimal tax rate, e.g. 0.19 for 19%
type: "product" | "shipping-costs"  // "shipping-costs" reserved; currently all lines are products
product: PunchOutProduct      // Embedded product master data (see below)
11}

Product-Data embedded in each PunchOutPosition. Sent to PunchCommerce so the procurement system can store/display the product even if the buyer's catalog doesn't have it.

1type PunchOutProduct = {
id: string                    // Internal product id (Medusa product_id) — informational
ordernumber: string           // SKU — duplicates PunchOutPosition.product_ordernumber
brand_ordernumber: string     // Manufacturer ordering reference; currently same as `ordernumber`
title: string                 // Full untruncated product title
description: string           // Plain-text product description
image_url?: string | null     // Variant or product thumbnail URL
price: number                 // Net unit price (mirrors PunchOutPosition.item_price)
currency: string              // ISO 4217 code, lowercase (e.g. "eur") — taken from the cart
tax_rate: number              // Same decimal value as PunchOutPosition.tax_rate
packaging_unit: string        // Hardcoded "Piece" today; future: per-variant mapping
shipping_time: number         // Hardcoded 0 today
active: "true" | "false"      // String (not boolean) — PunchCommerce convention
14
// Optional fields — not populated by this plugin yet, but accepted by PunchCommerce:
brand?: string
customer_ordernumber?: string
category?: string
description_long?: string
purchase_unit?: number
reference_unit?: number
unit?: string                 // OCI unit code, e.g. "PCE", "KG", "LTR"
unit_name?: string            // Human-readable unit name
weight?: number
classification_type?: string
classification?: string
27}

Top-level basket wrapper. This is the shape the PunchCommerce endpoint expects — when submitting the form, wrap the position array in .

1type PunchOutBasket = {
2  basket: PunchOutPosition[]
3}

Item passed to the action. The route parses the query string into an array of these.

1type PunchOutActionItem = {
2  sku: string
3  quantity: number
4}

Warning / info message returned alongside an action response (e.g. when a SKU in was not found).

1type PunchOutActionNotification = {
2  type: "info" | "warning"
3  message: string
4}

Discriminated union returned by . The storefront branches on to decide what to do next.

1type PunchOutActionResponse =
| { type: "default" }                                   // No action produced a result — proceed normally
| { type: "detail"; product_handle: string }            // Redirect the buyer to the PDP at this handle
| { type: "search"; keyword: string }                   // Redirect to your storefront's search page
| {                                                     // Inline-search PunchOut: submit the returned basket
    type: "background_search"
    basket: PunchOutPosition[]
    punchoutUrl: string
  }

Еще в этой категории

Посмотреть все

Другое

Gati

От Devx Commerce

Синхронизируйте Medusa с Gati ERP

Другое

Product Reviews

От Lambda Curry

Добавляйте рейтинги, отзывы и модерацию товаров

Другое

Variant Images

От Betanoir

Организуйте и загружайте варианты изображений в Medusa

Punchcommerce medusa plugin

PunchCommerce Plugin for Medusa

How It Works

Installation

Configuration

Options

Customer Setup

PunchCommerce Configuration

Storefront Requirements

1. Authentication route

2. Session-scoped cart

3. PunchOut Page (replaces checkout)

4. PunchOut Actions (optional)

Cart Mapping

Cart Lifecycle

Parallel Sessions

REST API Reference

GET /store/punchout/basket

GET /store/punchout/actions

GET | POST | DELETE /admin/customers/:id/punchcommerce-customer

Types Reference

PunchOutPosition

PunchOutProduct

PunchOutBasket

PunchOutActionItem

PunchOutActionNotification

PunchOutActionResponse

Еще в этой категории

Gati

Product Reviews

Variant Images

Punchcommerce medusa plugin

PunchCommerce Plugin for Medusa

How It Works

Installation

Configuration

Options

Customer Setup

PunchCommerce Configuration

Storefront Requirements

1. Authentication route

2. Session-scoped cart

3. PunchOut Page (replaces checkout)

4. PunchOut Actions (optional)

Cart Mapping

Cart Lifecycle

Parallel Sessions

REST API Reference

GET /store/punchout/basket

GET /store/punchout/actions

GET | POST | DELETE /admin/customers/:id/punchcommerce-customer

Types Reference

PunchOutPosition

PunchOutProduct

PunchOutBasket

PunchOutActionItem

PunchOutActionNotification

PunchOutActionResponse

Еще в этой категории

Gati

Product Reviews

Variant Images