payload-api

Payload Node.js Library

A Node.js library for integrating Payload.

Installation

Install using npm

npm install payload-api

Get Started

Once you've installed the Payload Node.js library to your environment, import the payload module to get started.

ESM

import payload from 'payload-api'

CommonJS

const pl = require('payload-api')

TypeScript

TypeScript declaration is in BETA. TypeScript import is the same as the ES Module import.

import payload from 'payload-api'

API Authentication

To authenticate with the Payload API, you'll need a live or test API key. API keys are accessible from within the Payload dashboard.

Create a Session:

import payload from 'payload-api'

// V1 API (default)
const pl = payload.Session('secret_key_12345')
// or explicitly specify V1
const plV1 = payload.Session('secret_key_12345', { apiVersion: 'v1' })

// V2 API
const plV2 = payload.Session('secret_key_12345', { apiVersion: 'v2' })

Creating an Object

Interfacing with the Payload API is done primarily through Payload Objects. Below is an example of creating a customer using the pl.Customer object.

Payload's Node.js API uses Promises.

// Create a Customer
const cust = await pl.create(pl.Customer({
  email: '[e-mail]',
  name: 'Matt Perez',
}))

// Create a Payment
const pmt = await pl.create(pl.Payment({
  amount: 100.0,
  payment_method: pl.Card({
    card_number: '4242 4242 4242 4242',
  })
}))

Updating an Object

Updating an object is a simple call to the update object method.

// Updating a customer's email
cust.update({ email: '[e-mail]' })

Selecting Objects

Objects can be selected using any of their attributes using filterBy.

// Select a customer by email
const results = pl.select(pl.Customer).filterBy({ email: '[e-mail]' })

Write complex queries using filter.

const results = pl.select(pl.Payment).filter(
    pl.Payment.amount.gt(100),
    pl.Payment.amount.lt(200),
    pl.or(
        pl.Payment.description.contains("Test1"),
        pl.Payment.description.contains("Test2")
    )
    pl.Payment.created_at.gt(new Date(2019,2,1))
)

Documentation

To get further information on Payload's Node.js library and API capabilities, visit the unabridged Payload Documentation.