MVMNT Credit Memos API
AR credit memo management operations. Credit memos represent customer credits that can be applied to invoices.
OpenAPI Specification
openapi: 3.1.0
info:
title: MVMNT Bill Payments Credit Memos API
version: 1.0.0
description: "The MVMNT API enables you to automate freight brokerage workflows by integrating\ndirectly with our Transportation Management System.\n\n## Authentication\n\nOAuth 2.0 client credentials flow. See [Authentication Guide](/getting-started/authentication)\nfor details.\n\n### Token Endpoint\n\n```\nPOST https://api.mvmnt.io/oauth2/token\n```\n\n#### Request\n\n**Headers:**\n```http\nContent-Type: application/x-www-form-urlencoded\n```\n\n**Body Parameters:**\n```\ngrant_type=client_credentials\nclient_id=YOUR_CLIENT_ID\nclient_secret=YOUR_CLIENT_SECRET\n```\n\n#### Example Request\n\n```bash\ncurl -X POST https://api.mvmnt.io/oauth2/token \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"grant_type=client_credentials\" \\\n -d \"client_id=YOUR_CLIENT_ID\" \\\n -d \"client_secret=YOUR_CLIENT_SECRET\"\n```\n\n#### Success Response\n\n**Status:** `200 OK`\n\n```json\n{\n \"access_token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 3600\n}\n```\n\n**Response Fields:**\n- `access_token`: JWT Bearer token to use for API requests\n- `token_type`: Always `Bearer`\n- `expires_in`: Token lifetime in seconds (3600 = 1 hour)\n"
contact:
name: MVMNT Support
email: support@mvmnt.io
url: https://docs.mvmnt.io
license:
name: Proprietary
url: https://mvmnt.io/legal/terms
x-parsed-md-description:
result:
- $$mdtype: Node
errors: []
lines:
- 0
- 2
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 0
- 2
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 0
- 2
inline: true
attributes:
content: The MVMNT API enables you to automate freight brokerage workflows by integrating
children: []
type: text
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 0
- 2
inline: true
attributes: {}
children: []
type: softbreak
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 0
- 2
inline: true
attributes:
content: directly with our Transportation Management System.
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: paragraph
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 3
- 4
inline: false
attributes:
level: 2
children:
- $$mdtype: Node
errors: []
lines:
- 3
- 4
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 3
- 4
inline: true
attributes:
content: Authentication
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: heading
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: true
attributes:
content: 'OAuth 2.0 client credentials flow. See '
children: []
type: text
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: true
attributes:
href: /getting-started/authentication
children:
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: true
attributes:
content: Authentication Guide
children: []
type: text
annotations: []
slots: {}
type: link
annotations: []
slots: {}
redocly:::linkOriginal:href: /getting-started/authentication
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: true
attributes:
content: ' for details.'
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: paragraph
annotations: []
slots: {}
servers:
- url: https://api.mvmnt.io/v1
description: Production
security:
- BearerAuth: []
tags:
- name: Credit Memos
description: 'AR credit memo management operations.
Credit memos represent customer credits that can be applied to invoices.
'
paths:
/credit-memos/filter:
post:
summary: Filter credit memos
description: 'Search for credit memos using filter criteria.
## Common Filters
- By customer: `{ "filter": { "customerId": { "equalTo": "uuid" } } }`
- With balance: `{ "filter": { "hasRemainingBalance": true } }`
- Open credits: `{ "filter": { "status": { "in": ["OPEN", "PARTIALLY_APPLIED"] } } }`
'
operationId: filterCreditMemos
tags:
- Credit Memos
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreditMemoFilterRequest'
examples:
byCustomer:
summary: Filter by customer
value:
filter:
customerId:
equalTo: 550e8400-e29b-41d4-a716-446655440000
availableCredits:
summary: Credits with balance
value:
filter:
hasRemainingBalance: true
status:
notEqualTo: VOIDED
responses:
'200':
description: Credit memos matching filter criteria
content:
application/json:
schema:
type: object
required:
- data
- pagination
properties:
data:
type: array
items:
$ref: '#/components/schemas/CreditMemo'
pagination:
$ref: '#/components/schemas/PaginationInfo'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'422':
$ref: '#/components/responses/ValidationError'
/credit-memos:
post:
summary: Create a credit memo
description: 'Create a new credit memo for a customer.
## Use cases
- Customer refunds
- Service adjustments
- Promotional credits
- Manual corrections
## Note
Credit memos from overpayments are created automatically
when a payment exceeds invoice totals.
'
operationId: createCreditMemo
tags:
- Credit Memos
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreditMemoInput'
examples:
refund:
summary: Customer refund
value:
customerId: 550e8400-e29b-41d4-a716-446655440000
amount: 500
currency: USD
memoDate: '2025-01-15'
reference: CM-00001
notes: Refund for damaged goods
adjustment:
summary: Service adjustment
value:
customerId: 550e8400-e29b-41d4-a716-446655440000
amount: 150
memoDate: '2025-01-15'
notes: Price adjustment per agreement
responses:
'201':
description: Credit memo created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreditMemo'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'422':
$ref: '#/components/responses/ValidationError'
/credit-memos/{id}:
get:
summary: Get a credit memo
description: 'Retrieve a credit memo by ID.
The response includes all applications showing how the credit has been used.
'
operationId: getCreditMemo
tags:
- Credit Memos
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
- $ref: '#/components/parameters/LookupBy'
responses:
'200':
description: Credit memo retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreditMemo'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
patch:
summary: Update a credit memo
description: 'Update credit memo fields.
## Constraints
- Amount cannot be changed if any applications exist
- Customer cannot be changed once created
'
operationId: updateCreditMemo
tags:
- Credit Memos
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
- $ref: '#/components/parameters/LookupBy'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreditMemoPatch'
examples:
updateReference:
summary: Update reference
value:
reference: CM-00001-REV
updateNotes:
summary: Update notes
value:
notes: 'Updated: Refund for damaged goods and shipping issues'
responses:
'200':
description: Credit memo updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreditMemo'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'422':
$ref: '#/components/responses/ValidationError'
/credit-memos/{id}/void:
post:
summary: Void a credit memo
description: 'Void/cancel a credit memo.
## Prerequisites
- Credit memo must have no applications (full balance remaining)
- Must unapply all applications before voiding
## What happens
- Credit memo status changes to VOIDED
- Credit is no longer available for application
- QBO sync will delete the credit memo
'
operationId: voidCreditMemo
tags:
- Credit Memos
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
- $ref: '#/components/parameters/LookupBy'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/VoidCreditMemoRequest'
examples:
withReason:
summary: Void with reason
value:
reason: Credit issued in error
responses:
'200':
description: Credit memo voided successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreditMemo'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'409':
description: Cannot void - credit memo has applications
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Error'
/credit-memos/{id}/apply:
post:
summary: Apply credit to invoice
description: 'Apply credit memo amount to an invoice.
## What happens
- Creates credit application record
- Reduces credit memo remaining balance
- Reduces invoice open balance
- Updates order status if invoice is fully paid
## Constraints
- Amount must not exceed remaining balance
- Invoice must belong to same customer
- Invoice must have outstanding balance
- Currency must match
'
operationId: applyCreditMemo
tags:
- Credit Memos
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
- $ref: '#/components/parameters/LookupBy'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApplyCreditRequest'
examples:
applyCredit:
summary: Apply credit
value:
invoiceId: 660e8400-e29b-41d4-a716-446655440001
amount: 200
responses:
'200':
description: Credit applied successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ApplyCreditResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'409':
description: Cannot apply - insufficient balance or invalid invoice
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Error'
'422':
$ref: '#/components/responses/ValidationError'
/credit-memos/{id}/applications:
get:
summary: Get credit applications
description: List all invoice applications for a credit memo.
operationId: getCreditMemoApplications
tags:
- Credit Memos
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
- $ref: '#/components/parameters/LookupBy'
responses:
'200':
description: Applications retrieved successfully
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/CreditMemoApplication'
totalApplied:
type: number
remainingBalance:
type: number
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
/credit-memos/{creditMemoId}/applications/{applicationId}:
delete:
summary: Unapply credit from invoice
description: 'Remove a credit application from an invoice.
## What happens
- Application record is deleted
- Credit memo remaining balance increases
- Invoice open balance increases
- Order status may revert if invoice becomes unpaid
'
operationId: unapplyCreditMemo
tags:
- Credit Memos
parameters:
- name: creditMemoId
in: path
required: true
schema:
type: string
description: Credit memo ID
- name: applicationId
in: path
required: true
schema:
type: string
format: uuid
description: Application ID
responses:
'200':
description: Credit unapplied successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreditMemo'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
components:
schemas:
FloatFilter:
type: object
description: Filter options for float/number fields
properties:
equalTo:
type: number
format: float
description: Exact match
notEqualTo:
type: number
format: float
description: Not equal to
lessThan:
type: number
format: float
description: Less than
lessThanOrEqualTo:
type: number
format: float
description: Less than or equal to
greaterThan:
type: number
format: float
description: Greater than
greaterThanOrEqualTo:
type: number
format: float
description: Greater than or equal to
isNull:
type: boolean
description: Field is null (true) or not null (false)
CreditMemo:
type: object
required:
- id
- amount
- remainingBalance
- status
- memoDate
- createdAt
properties:
id:
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
key:
type:
- string
- 'null'
description: Client-defined key
reference:
type:
- string
- 'null'
description: Reference number
example: CM-00001
customer:
$ref: '#/components/schemas/CustomerReference'
amount:
type: number
description: Original credit amount
appliedAmount:
type: number
description: Total amount applied to invoices
remainingBalance:
type: number
description: Available balance
currency:
type:
- string
- 'null'
description: Currency code
example: USD
status:
$ref: '#/components/schemas/CreditMemoStatus'
memoDate:
type: string
format: date
description: Credit memo date
notes:
type:
- string
- 'null'
description: Notes or description
sourcePaymentGroupId:
type:
- string
- 'null'
format: uuid
description: Payment that created this credit (if from overpayment)
sourcePaymentKey:
type:
- string
- 'null'
applications:
type: array
items:
$ref: '#/components/schemas/CreditMemoApplication'
description: Invoices this credit is applied to
qboId:
type:
- string
- 'null'
description: QuickBooks Online credit memo ID
createdAt:
type: string
format: date-time
updatedAt:
type:
- string
- 'null'
format: date-time
voidedAt:
type:
- string
- 'null'
format: date-time
voidReason:
type:
- string
- 'null'
createdBy:
$ref: '#/components/schemas/UserReference'
ApplyCreditRequest:
type: object
required:
- invoiceId
- amount
properties:
invoiceId:
type: string
format: uuid
description: Invoice to apply credit to
amount:
type: number
minimum: 0.01
description: Amount to apply
ValidationError:
type: object
required:
- error
- message
- details
properties:
error:
type: string
description: Error code
example: validation_error
message:
type: string
description: Human-readable error message
details:
type: array
description: Validation error details
items:
type: object
required:
- field
- message
properties:
field:
type: string
description: Field name that failed validation
message:
type: string
description: Validation error message
CreditMemoStatusFilter:
type: object
properties:
equalTo:
$ref: '#/components/schemas/CreditMemoStatus'
notEqualTo:
$ref: '#/components/schemas/CreditMemoStatus'
in:
type: array
items:
$ref: '#/components/schemas/CreditMemoStatus'
Error:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code
message:
type: string
description: Human-readable error message
PaginationInfo:
type: object
required:
- pageSize
- hasNextPage
properties:
pageSize:
type: integer
description: Number of items per page
example: 50
hasNextPage:
type: boolean
description: Whether there are more pages
example: true
hasPreviousPage:
type: boolean
description: Whether there are previous pages
example: false
endCursor:
type:
- string
- 'null'
description: Cursor for the next page (null if no next page)
example: eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9
CreditMemoFilterRequest:
type: object
properties:
filter:
$ref: '#/components/schemas/CreditMemoFilter'
pageSize:
type: integer
minimum: 1
maximum: 100
default: 50
cursor:
type: string
CreditMemoApplication:
type: object
required:
- id
- invoiceId
- amount
properties:
id:
type: string
format: uuid
invoiceId:
type: string
format: uuid
invoiceFriendlyId:
type:
- string
- 'null'
paymentId:
type: string
format: uuid
description: Payment through which this credit was applied
paymentKey:
type:
- string
- 'null'
amount:
type: number
description: Amount applied
appliedAt:
type: string
format: date-time
UUIDFilter:
type: object
description: Filter options for UUID fields (all operations)
properties:
equalTo:
type: string
format: uuid
description: Exact match
notEqualTo:
type: string
format: uuid
description: Not equal to
in:
type: array
items:
type: string
format: uuid
description: Matches any UUID in the array
notIn:
type: array
items:
type: string
format: uuid
description: Does not match any UUID in the array
isNull:
type: boolean
description: Field is null (true) or not null (false)
CreditMemoPatch:
type: object
properties:
reference:
type:
- string
- 'null'
notes:
type:
- string
- 'null'
memoDate:
type: string
format: date
VoidCreditMemoRequest:
type: object
properties:
reason:
type: string
maxLength: 1000
description: Reason for voiding
CustomerReference:
type: object
description: 'Enhanced reference to a customer resource (returned in responses).
Includes full customer details in addition to id/key.
Note: Does NOT include nested references (paymentTerm, contacts, etc.) to prevent recursion.
Maximum nesting depth: 1 level.
'
required:
- id
- name
- friendlyId
- status
- createdAt
- updatedAt
properties:
id:
type: string
format: uuid
description: Customer UUID
example: 550e8400-e29b-41d4-a716-446655440000
key:
type:
- string
- 'null'
maxLength: 512
description: Client-defined reference ID if set
example: ERP-CUSTOMER-ACME
name:
type: string
description: Customer company name
example: Acme Manufacturing Corp
friendlyId:
type: string
description: Human-readable customer identifier
example: A123456
status:
type: string
description: Customer status
enum:
- PROSPECT
- ACTIVE
- INACTIVE
- CHURNED
example: ACTIVE
phoneNumber:
type:
- string
- 'null'
description: Primary phone number
example: +1-555-123-4567
website:
type:
- string
- 'null'
description: Customer website URL
example: https://acme-manufacturing.com
createdAt:
type: string
format: date-time
description: When the customer was created
example: '2025-01-15T10:00:00Z'
updatedAt:
type: string
format: date-time
description: When the customer was last updated
example: '2025-01-15T14:30:00Z'
deletedAt:
type:
- string
- 'null'
format: date-time
description: When the customer was soft deleted (null if active)
example: null
DatetimeFilter:
type: object
description: Filter options for datetime fields
properties:
equalTo:
type: string
format: date-time
description: Exact match
notEqualTo:
type: string
format: date-time
description: Not equal to
lessThan:
type: string
format: date-time
description: Before this datetime
lessThanOrEqualTo:
type: string
format: date-time
description: On or before this datetime
greaterThan:
type: string
format: date-time
description: After this datetime
greaterThanOrEqualTo:
type: string
format: date-time
description: On or after this datetime
isNull:
type: boolean
description: Field is null (true) or not null (false)
UserReference:
type: object
description: 'Enhanced reference to a user resource (returned in responses).
Includes full user details in addition to id/key.
Note: Does NOT include nested references (teams, etc.) to prevent recursion.
Maximum nesting depth: 1 level.
'
required:
- id
- email
- status
- createdAt
- updatedAt
properties:
id:
type: string
format: uuid
description: User UUID
example: 550e8400-e29b-41d4-a716-446655440000
key:
type:
- string
- 'null'
maxLength: 512
description: Client-defined reference ID if set
example: ERP-USER-12345
email:
type: string
format: email
description: User's email address
example: john.doe@example.com
name:
type:
- string
- 'null'
description: User's full name
example: John Doe
phone:
type:
- string
- 'null'
description: User's phone number
example: +1-555-123-4567
phoneExt:
type:
- string
- 'null'
description: Phone extension
example: '123'
status:
type: string
description: User account status
enum:
- PENDING
- ACTIVE
- INACTIVE
example: ACTIVE
avatarId:
type:
- string
- 'null'
format: uuid
description: Profile avatar document ID
example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
createdAt:
type: string
format: date-time
description: When the user was created
example: '2025-01-15T10:00:00Z'
updatedAt:
type: string
format: date-time
description: When the user was last updated
example: '2025-01-15T14:30:00Z'
deletedAt:
type:
- string
- 'null'
format: date-time
description: When the user was soft deleted (null if active)
example: null
CreditMemoInput:
type: object
required:
- customerId
- amount
- memoDate
properties:
customerId:
type: string
format: uuid
description: Customer to credit
amount:
type: number
minimum: 0.01
description: Credit amount
currency:
type: string
description: Currency code (defaults to customer currency)
memoDate:
type: string
format: date
description: Credit memo date
reference:
type: string
maxLength: 500
description: Reference number
notes:
type: string
maxLength: 2000
description: Notes or description
CreditMemoFilter:
type: object
properties:
id:
$ref: '#/components/schemas/UUIDFilter'
customerId:
$ref: '#/components/schemas/UUIDFilter'
status:
$ref: '#/components/schemas/CreditMemoStatusFilter'
memoDate:
$ref: '#/components/schemas/DatetimeFilter'
amount:
$ref: '#/components/schemas/FloatFilter'
remainingBalance:
$ref: '#/components/schemas/FloatFilter'
hasRemainingBalance:
type: boolean
description: Filter to credits with available balance
sourcePaymentGroupId:
$ref: '#/components/schemas/UUIDFilter'
createdAt:
$ref: '#/components/schemas/DatetimeFilter'
and:
type: array
items:
$ref: '#/components/schemas/CreditMemoFilter'
or:
type: array
items:
$ref: '#/components/schemas/CreditMemoFilter'
not:
$ref: '#/components/schemas/CreditMemoFilter'
CreditMemoStatus:
type: string
enum:
- OPEN
- PARTIALLY_APPLIED
- APPLIED
- VOIDED
description: 'Current status of the credit memo (derived from remaining balance).
- `OPEN`: No applications, full balance available
- `PARTIALLY_APPLIED`: Some amount applied, balance remains
- `APPLIED`: Fully applied to invoices
- `VOIDED`: Credit memo cancelled
'
ApplyCreditResponse:
type: object
required:
- application
- creditMemo
properties:
application:
$ref: '#/components/schemas/CreditMemoApplication'
creditMemo:
$ref: '#/components/schemas/CreditMemo'
responses:
NotFoundError:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: not_found
message: Resource not found
ValidationError:
description: Validation error - invalid field values
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
example:
error: validation_error
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mvmnt/refs/heads/main/openapi/mvmnt-credit-memos-api-openapi.yml